dapr / dapr/docs

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

Open
#5,142 0 comments 0 reactions 0 assignees View on GitHub
documentation
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.