Hugo Docs Server
ADR documents are served by a Hugo dev server at port 1318; supersedes the file:// constraint in ADR-003.
Context
ADR-003 established that all research and ADR documents must be openable directly
from file:// with no running server, because the backend did not exist
yet and prototypes needed zero-setup sharing.
The project now has a running backend (SAM local + LocalStack), a tmuxinator-managed
dev session, and a Hugo site at docs/site/. The prototype phase is complete.
The team always works inside the same tmux session, so a running Hugo server is a
natural part of the dev environment.
The docs/site/ Hugo site provides ADR navigation, live reload, module-mounted
research docs, and consistent styling through shared layout templates — none of which
are achievable from file://.
Decision
The canonical docs experience is the Hugo dev server at
http://localhost:1318, started via task docs:dev (pane 6 of
the tmux session). This supersedes the requirement in ADR-003 that docs must work
without a server.
The standalone HTML files under docs/adr/ and docs/research/
are retained as a file:// fallback. They continue to be mounted as
static assets in the Hugo site and must be kept in sync with their Hugo content
counterparts under docs/site/content/.
New ADRs must be created in both locations: a standalone HTML file in
docs/adr/adr-NNN-*/index.html and a Hugo content file in
docs/site/content/adr/NNN-*.html.
Consequences
Positive
- Proper ADR index with navigation between documents
- Live reload during authoring (
task docs:dev) - Consistent styling via shared Hugo layout templates
- Module mounts expose research docs at stable URLs
file://fallback is preserved for the raw HTML files
Negative
- Canonical experience requires
task docs:devto be running - Hugo must be installed (already a project dependency)
- New ADRs require two files — standalone HTML and Hugo content — that must stay in sync
Alternatives Considered
| Option | Why not chosen |
|---|---|
| Keep file:// only (ADR-003 unchanged) | No navigation index, no live reload, no cross-ADR linking via Hugo; the Hugo site already exists and is in the tmux session |
| Migrate docs into the Hugo catalog site (port 1317) | Keeps ADR/research content separate from the product demo site; a dedicated docs server is easier to restart independently |
| Single source of truth: Hugo only, drop the standalone HTML files | Loses the zero-setup sharing property that is still useful for ad-hoc review; the standalone files cost little to maintain |