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:
parent
9f06899238
commit
60042d877e
4 changed files with 48 additions and 186 deletions
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Reference in a new issue