↓Skip to main content

ADR 0001 — Hugo over Astro

ADR 0001 — Hugo over Astro #

Status: Accepted · Date: 2024-01 (recorded retroactively 2026-04)

Context #

We needed a static site for LUSTECH. Constraints:

  • Bilingual (Swedish default, English secondary), 5–10 pages today, blog posts planned
  • One person maintaining it; no dedicated frontend specialist
  • Self-hosted on Coolify; no Vercel-specific tricks
  • Build pipeline must work for years without npm rot

The realistic candidates were Hugo, Astro, Next.js (static export), and Eleventy.

Decision #

Hugo with the PaperMod theme.

PaperMod gives us ~90% of what a consultancy site needs out of the box: profile mode, multilingual menus, RSS, mobile-friendly typography, JSON-LD scaffolding. Hugo’s i18n story is mature — translationKey linking, per-language contentDir, per-language menus — and ships with the binary.

We rejected:

  • Astro. Excellent when you need to embed React/Vue/Svelte components with selective hydration. We don’t. The “islands” model is overhead for a site whose interactivity is a theme toggle and a contact form.
  • Next.js static export. Adds a heavy JS toolchain and React knowledge requirement for content-only pages. The marginal benefit over Hugo is zero for our content shape.
  • Eleventy. Reasonable, but PaperMod doesn’t exist for it. We’d be building most of the theme ourselves.

Consequences #

  • ✅ Builds in ~70 ms; CI is fast and trustworthy
  • ✅ Zero JavaScript shipped for content pages
  • ✅ No package.json, no node_modules, no Node version drift across years
  • ✅ Markdown-first content workflow; the source of truth is portable
  • ⚠️ Go templates are more verbose than JSX; advanced layout work means writing more lines
  • ⚠️ If we later need rich client-side interactivity (live previews, dashboards), we’ll either add a framework on top or reach for Astro at that point

Status #

Accepted, in production.