Docsy v2 upgrade on legacy branches causes build output >250MB, requires Standard SKU
- 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
Assessment
This issue has not been assessed yet.