docs(options): emit markdown only, render HTML in website

Per #1407 review: the options reference should be markdown here; the
HTML + CSS belongs in the website repo where the theme lives and the
stylesheet can be shared with /docs.

- nix/docs/default.nix: drop the cmark-gfm HTML rendering, the inline
  <style>, and the HTML index. Emit index.md + host.md + agent.md only
  (CommonMark from nixosOptionsDoc).
- Remove nix/docs/style.css.
- Update docs/gotchas.md + CLAUDE.md to describe the md-only output and
  point at the website for HTML rendering.

The website (hyperhive/website#26) renders these .md to themed HTML for
/options/, sharing one docs.css with the prose /docs/ tree.
This commit is contained in:
iris 2026-06-05 19:29:07 +02:00 committed by mara
commit 60042d877e
4 changed files with 48 additions and 186 deletions

View file

@ -286,29 +286,24 @@ inputs stay out of the eval) and `agentEval` (reuses the already-evaluated
`agent-base` container config so the per-agent options tree is
identical to what a real agent container sees).
Three output trees consumed by `flake.nix`:
Three output trees consumed by `flake.nix`, all **markdown**:
- `docs-host` — operator-facing host module options
(`services.hyperhive.*`)
- `docs-agent` — per-agent harness options (`hyperhive.*`
declared in `nix/templates/harness-base.nix`)
- `docs` — bundled static site (`index.html` + `host.html` +
`agent.html`, plus `.md` source-of-truth versions of each
options page)
- `docs` — bundle of `index.md` + `host.md` + `agent.md`
Rendering pipeline:
Pipeline:
- CommonMark from `nixosOptionsDoc.optionsCommonMark` — source of
truth, kept as `.md` in the bundle.
- HTML via `pkgs.cmark-gfm` over the CommonMark, wrapped in a
minimal inline-CSS template. `cmark-gfm` (not plain `cmark`) so
any future tables / autolinks Just Work without revisiting.
- Inline `<style>` from `nix/docs/style.css` so the bundle is
single-file-per-page and nginx's `/options/` mount needs no MIME
setup for separate `.css` files and no cache-busting.
- Asset paths inside rendered HTML are all relative
(`./host.html`, etc.) so the bundle can mount at any URL prefix
without rewriting.
- CommonMark from `nixosOptionsDoc.optionsCommonMark` is the only
output — the source of truth, emitted as `.md`.
- **HTML + CSS is rendered downstream by the website repo**
(`nix/options.nix` there), which consumes this bundle's `host.md` /
`agent.md`, renders them with `cmark-gfm`, and shares one
stylesheet (`docs.css`) across `/options/` and the prose `/docs/`
tree. Keeping rendering in the website means the theme has a single
home and the colours are shared.
- `transformOptions` strips the nix-store prefix from option
declaration paths and rewrites them as forge URLs, so the
rendered docs link back to the source.