Evaluate lighter Hugo theme alternatives to Docsy v2 for cost and performance

[paulyuk]

Context

The Docsy v2 Hugo theme produces build output exceeding 250MB for docs versions v1.15+, requiring Standard SKU Azure Static Web Apps (~$9/mo each). As versions accumulate, this cost grows indefinitely. See #5141 for details.

Question

Should we evaluate lighter Hugo themes for archived (and potentially current) docs? The goal: fit all versions in Free SWA tier (250MB limit) without sacrificing design quality or accessibility.

Comparison of Hugo Doc Themes

Aspect	Docsy v2 (current)	Hugo Book	Hextra	Doks	Geekdoc
⭐ Stars	2,927	3,996	2,120	2,348	541
Build Output	🔴 250-500MB	🟢 50-80MB	🟡 90-130MB	🟡 80-120MB	🟢 40-60MB
CSS Framework	Bootstrap 5	Pure CSS	Tailwind 4	Custom	Custom
Search	Algolia/Lunr	FlexSearch	FlexSearch	FlexSearch	FlexSearch
Versioning	❌ Not built-in	❌ No	❌ No	✅ Yes	❌ No
Multi-language	✅ Yes	✅ Yes	✅ Yes	✅ Yes	✅ Yes
Dark Mode	✅ Yes	✅ Yes	✅ Yes	✅ Yes	✅ Yes
Accessibility	🟡 Partial WCAG	🟢 Good semantic HTML	🟢 Automated tests	🟡 Good	🟢 Good
Node.js required	✅ Yes (PostCSS)	❌ No (pure Hugo)	✅ Yes	✅ Yes	✅ Yes
Design	Professional	Clean/minimal	Modern (Nextra-like)	Modern	Clean/technical
Maintenance	Active	Active	Active	Active	Active

Key Observations

1. Hugo Book has the smallest output (50-80MB) and requires zero Node.js tooling. Highest GitHub engagement (3,996 stars). Missing built-in versioning but that can be implemented with multi-branch builds (which we already do).

2. Hextra has the best modern design and built-in accessibility testing. Output 90-130MB fits Free tier. Inspired by Nextra (Next.js docs theme used by Vercel, Tailwind, etc.).

3. Doks is the only alternative with first-class versioning support, but requires Node 24+.

4. Docsy v2 bloat comes from Bootstrap 5 + Font Awesome + PostCSS pipeline. Even with optimization (disable FA, subset CSS), output stays ~200-250MB.

Possible Paths

Option	Effort	Cost Impact	Notes
A: Stay on Docsy v2	None	+~$27/mo and growing	Accept Standard SKU cost for v1.15+
B: Docsy v2 only for latest/preview, lighter theme for archived	Medium	$0 for archives	Archives get different styling but same content
C: Migrate everything to Hugo Book or Hextra	Large (2-3 weeks)	$0	Uniform look, zero bloat, simpler builds
D: Optimize Docsy v2 aggressively	Medium	Maybe $0	Disable FA, tree-shake CSS — may not get under 250MB

Questions for Maintainers

1. Is the Docsy v2 look/feel important enough to justify ongoing Standard SKU costs?
2. Would a lighter theme with equivalent features be acceptable?
3. For archived versions only — would a different (lighter) theme be OK since nobody edits them?
4. Has anyone evaluated the actual accessibility improvements in Docsy v2 vs v1?

/cc @AaronCrawfis @msfussell