Evaluate lighter Hugo theme alternatives to Docsy v2 for cost and performance
- Dominant language
- SCSS
- Stars
- 1k
- Forks
- 794
- Avg merge
- 2d 8h
- Merged PRs (30d)
- 7
Description
## 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
Contributor guide
Assessment
This issue has not been assessed yet.