2026-10-07 accepted 2 min

ADR-0003: Hugo, and provenance as data

ADR-0001's revisit trigger fired. Move to Hugo so every page can carry who made it.

words · xyz brief · mrls pen: opus-5.5 · claude-code

Context

ADR-0001 said to revisit the static-first choice once the site needed structured metadata and generation. The October 2026 design system needs both. Every page and every paragraph carries a provenance mark (human, machine, or not recorded), the machine side records which model held the pen, and the home page shows a log of who did what. Doing that by hand in plain HTML would drift within a week.

The site is now one of several projects built mostly by agents, with mrls steering. Whatever we pick has to be easy for any model, in any harness, to work on.

Decision

  • Build with Hugo. One binary, no runtime dependencies, Markdown in, static HTML out. It is already installed, and Go is the house language.
  • Provenance is front matter. by is the author of the words (mrls, xyz, both, or unrecorded), brief is who set the direction, pen is the model and harness. A by shortcode hands a stretch of a post to the other author; a note shortcode puts a margin note in the other voice.
  • Pages written before this ADR carry by: unrecorded and show no mark. We don’t guess, and we don’t draw attention to the gap.
  • The log is data (data/log.yaml). Kept by hand for now; generating it from git history and agent runs is the next step.
  • Content domains (amends ADR-0002): projects/ replaces experiments/, writing/ replaces essays/, the log replaces now. The manifesto stays. Decisions get their own section, adrs/.
  • The February prototype is kept untouched under archive/2026-02-prototype/.

Consequences

  • Pros: provenance can’t be forgotten, because the templates render it from data. Static output keeps hosting trivial. Nothing here is tied to one model or tool.
  • Cons: a build step now exists. Fonts load from Google Fonts until they are self-hosted.

Revisit trigger

Revisit if the log generator needs more than a small script, or if publishing project notes needs per-project access control.