dapr / dapr/docs

Docsy v2 upgrade on legacy branches causes build output >250MB, requires Standard SKU

Open
#5,141 2 comments 0 reactions 0 assignees View on GitHub
documentation
Dominant language
SCSS
Stars
1k
Forks
794
Avg merge
2d 8h
Merged PRs (30d)
7

Description

## Problem

PRs [#4733](https://github.com/dapr/docs/pull/4733) and [#4793](https://github.com/dapr/docs/pull/4793) upgraded Hugo and Docsy across multiple versioned branches (including v1.15, v1.16, v1.17). This upgrade:

1. **Changed Hugo from 0.100.2 → 0.147.9**
2. **Upgraded Docsy theme to v2** (Hugo modules instead of git submodules)
3. **Changed workflow structure** to pre-build Hugo externally instead of using SWA's built-in Hugo build
4. **Updated content and theme files** on the branches, making the change irreversible without significant effort

### Impact: Build output now exceeds Azure SWA Free tier 250MB limit

| Version | Original Hugo | Current Hugo | Free Tier Deploy |
|---------|--------------|-------------|-----------------|
| v1.14 and older | 0.100.2 | 0.100.2 | ✅ Fits under 250MB |
| v1.15 | 0.100.2 | 0.147.9 (Docsy v2) | ❌ Exceeds 250MB |
| v1.16 | 0.100.2 | 0.147.9 (Docsy v2) | ❌ Exceeds 250MB |
| v1.17 | 0.100.2 | 0.147.9 (Docsy v2) | ❌ Exceeds 250MB |

This means v1.15–v1.17 **require Standard SKU (\/month each = \/month)** to deploy. As new versions are released, every new archived version will also require Standard, making this cost grow indefinitely.

### Questions for maintainers

1. **What was the benefit of upgrading Hugo/Docsy on archived version branches?** These are read-only historical docs. Was there a rendering bug, security issue, or feature that required the upgrade?

2. **Is the benefit worth the ongoing cost?** Each archived version that exceeds 250MB requires a Standard SWA (~\/month). Over time this compounds:
- Today: 3 extra Standard SWAs = ~\/month
- After v1.19 release: 4 extra = ~\/month
- Pattern continues with each release

3. **Should we revert the Docsy v2 upgrade on legacy branches?** This would require reverting both the workflow files AND the theme/content changes from PRs #4733 and #4793 on branches v1.15–v1.17. The original Hugo 0.100.2 + Docsy v1 output fits comfortably in the Free tier.

4. **Alternative: Can we optimize Docsy v2 output size?** If there's a way to reduce the Hugo 0.147.9 + Docsy v2 build output below 250MB (e.g., excluding unused assets, tree-shaking CSS/JS, or reducing generated page count), that would solve the problem without reverting.

### Context

- We are migrating SWAs to a new Azure subscription after the old one was deactivated
- The [SKU policy](https://gist.github.com/paulyuk/a4e92bf4477b7f040df5bae8aa045ecc) aims to keep only 3 SWAs on Standard (root, blog, newest preview) to control costs
- v1.14 and older deploy successfully on Free tier using the original Hugo 0.100.2 workflow
- Related PRs: #5132–#5140 (workflow_dispatch fix + deployment to new SWAs)

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.