Evaluate lighter Hugo theme alternatives to Docsy v2 for cost and performance
I maintainer di solito rispondono entro 9 giorni
Nessuno ha ancora preso questa issue.
Valutazione
- Difficoltà
- 5/5
- Tempo stimato
- Più di una settimana
- Idoneità per principianti
- 35/100
- Tipo di issue
- Funzionalità
- Chiarezza
- Da chiarire
- Stato di attività
- Tranquilla
- Stack tecnologico
- azure, hugo, node.js, scss, tailwind
- Ambito
- build-system, cloud, documentation, performance
Direzione di ricerca
Non sono indicati file sorgente né test; inizia leggendo #5141 e verificando le dimensioni documentate delle build Hugo e il limite del piano di Azure Static Web Apps per le opzioni di tema elencate. Il lavoro è considerato completato quando un maintainer registra una decisione sull’opportunità di valutare un tema più leggero o di eseguire la migrazione a uno di essi, includendo l’ambito accettato e i criteri relativi ad accessibilità, design, versioning e costi.
Scritto dal modello di indicizzazione a partire dal testo della issue.
Descrizione
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
-
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).
-
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.).
-
Doks is the only alternative with first-class versioning support, but requires Node 24+.
-
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
- Is the Docsy v2 look/feel important enough to justify ongoing Standard SKU costs?
- Would a lighter theme with equivalent features be acceptable?
- For archived versions only — would a different (lighter) theme be OK since nobody edits them?
- Has anyone evaluated the actual accessibility improvements in Docsy v2 vs v1?
/cc @AaronCrawfis @msfussell
- Lingua principale
- SCSS
- Stelle
- 1k
- Fork
- 796
- Merge medio
- 3g 6h
- PR unite (30g)
- 17
Preparare l'ambiente
Come iniziare
- Leggi tutta la issue e poi la guida ai contributi del progetto.
- Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
- Fai un fork del repository e lavora su un branch.
- Apri una pull request che faccia riferimento al numero della issue.
Altre issue di dapr/docs
-
Difficoltà 2/5 1-3 ore Idoneità per principianti 85/100
I maintainer di solito rispondono entro 9 giorni
-
content/missing-information
Difficoltà 1/5 1-3 ore Idoneità per principianti 88/100
I maintainer di solito rispondono entro 9 giorni
-
Difficoltà 2/5 1-3 ore Idoneità per principianti 78/100
I maintainer di solito rispondono entro 9 giorni
-
content/incorrect-information
Difficoltà 1/5 Meno di un'ora Idoneità per principianti 88/100
I maintainer di solito rispondono entro 9 giorni
-
Difficoltà 2/5 1-3 ore Idoneità per principianti 78/100
I maintainer di solito rispondono entro 9 giorni
Issue simili
-
Difficoltà 1/5 Meno di un'ora Idoneità per principianti 92/100
HarperFast/harper#2860 ·
I maintainer di solito rispondono entro 1 giorno
-
Difficoltà 1/5 Meno di un'ora Idoneità per principianti 92/100
anthropics/skills#1893 · 1 commento ·
I maintainer di solito rispondono entro 1 giorno
-
pnpm install exits 1: MemoryCore/pnpm-workspace.yaml ships "set this to true or false" placeholdersAperta
Difficoltà 2/5 1-3 ore Idoneità per principianti 85/100
TencentCloud/TencentDB-Agent-Memory#1544 · 1 commento ·
I maintainer di solito rispondono entro 1 giorno
-
Difficoltà 2/5 1-3 ore Idoneità per principianti 78/100
YosysHQ/oss-cad-suite-build#216 ·
-
Difficoltà 2/5 1-3 ore Idoneità per principianti 74/100
openwatersio/slackwater.xyz#124 ·
I maintainer di solito rispondono entro 1 giorno