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

[paulyuk]

Problem

PRs #4733 and #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 Upgrade hugo docsy into 1.16 #4733 and Ensure minification of output #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 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: fix: allow workflow_dispatch for v1.18 SWA deployment #5132–fix: allow workflow_dispatch for v1.10 SWA deployment #5140 (workflow_dispatch fix + deployment to new SWAs)

[paulyuk]

Update: v1.16 upgraded to Standard, v1.17 skipped

After extensive testing, the Docsy v2 build output for v1.16 and v1.17 cannot be reduced below 250MB even with:

• Removing all zh-hans translations
• Removing Font Awesome SVG/sprite source files
• Removing Bootstrap test/site files
• Disabling RSS, sitemap, taxonomy generation (--disableKinds)

v1.16: Upgraded to Standard SKU. Needs a proper fix — either revert PR #4733 on the v1.16 branch (all 100 files) to restore Hugo 0.100.2 + Docsy v1, or find a way to optimize Docsy v2 output below 250MB.

v1.17: Skipped. v1.17 content is already served by \dapr-docs-root\ (Standard) at docs.dapr.io, so a separate v1-17.docs.dapr.io SWA is redundant. We'll remove v1.17 from the version selector since latest already covers it.

Versions that fit Free tier: v1.10–v1.15 all pass after removing translations and disabling RSS/sitemap.

See also #5142 for evaluation of lighter Hugo theme alternatives.

[marcduiker]

The main reason for upgrading Hugo (and Docsy) was to make it as easy as possible for others to contribute. Contributors should not need to worry about installing an outdated version of Hugo. I suggest to go for an alternative theme as you already researched with #5142.