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
mara
parent
9f06899238
commit
60042d877e
4 changed files with 48 additions and 186 deletions
|
|
@ -5,10 +5,11 @@
|
|||
nixosSystem,
|
||||
}:
|
||||
# Nix options reference: `pkgs.nixosOptionsDoc` over two evaluated
|
||||
# module trees, rendered as CommonMark + HTML + bundled static site
|
||||
# the operator's nginx serves from `/options/`. Full pipeline +
|
||||
# subtree-pick / output-tree rationale: docs/gotchas.md::Nix options
|
||||
# reference.
|
||||
# module trees, emitted as CommonMark (`host.md` + `agent.md`). The
|
||||
# HTML + CSS for `/options/` is rendered downstream by the website
|
||||
# repo, which owns the presentation and shares one stylesheet with the
|
||||
# prose `/docs/` tree. Full pipeline + subtree-pick / output-tree
|
||||
# rationale: docs/gotchas.md::Nix options reference.
|
||||
let
|
||||
# Stub host system: every hyperhive subsystem `mkForce false` so
|
||||
# heavy build inputs (matrix container, forge, etc.) stay out of
|
||||
|
|
@ -102,7 +103,10 @@ let
|
|||
inherit transformOptions;
|
||||
};
|
||||
|
||||
# CommonMark .md = source of truth; HTML is rendered from this.
|
||||
# CommonMark `.md` is the source of truth and the only output. HTML
|
||||
# rendering + theming lives in the website repo (it owns the
|
||||
# presentation + shares one stylesheet across `/options/` and
|
||||
# `/docs/`); this flake just emits the option reference as markdown.
|
||||
mkMarkdownPage =
|
||||
name: title: doc:
|
||||
pkgs.runCommand "hyperhive-${name}.md" { } ''
|
||||
|
|
@ -117,100 +121,39 @@ let
|
|||
} > $out
|
||||
'';
|
||||
|
||||
# Loaded as text so it's editable with normal CSS tooling and
|
||||
# inlined into every page (no second-fetch dependency).
|
||||
styleCSS = builtins.readFile ./style.css;
|
||||
# Bundle landing page — a short markdown index pointing at the two
|
||||
# reference pages.
|
||||
indexMD = pkgs.writeText "hyperhive-options-index.md" ''
|
||||
# hyperhive — nix options reference
|
||||
|
||||
# CommonMark → cmark-gfm → minimal template, inline CSS, relative links.
|
||||
mkHtmlPage =
|
||||
name: title: doc:
|
||||
pkgs.runCommand "hyperhive-${name}.html" { nativeBuildInputs = [ pkgs.cmark-gfm ]; } ''
|
||||
{
|
||||
echo '<!doctype html>'
|
||||
echo '<html lang="en">'
|
||||
echo '<head>'
|
||||
echo '<meta charset="utf-8">'
|
||||
echo '<meta name="viewport" content="width=device-width, initial-scale=1">'
|
||||
echo '<title>${title}</title>'
|
||||
echo '<style>'
|
||||
cat ${pkgs.writeText "hyperhive-docs-style.css" styleCSS}
|
||||
echo '</style>'
|
||||
echo '</head>'
|
||||
echo '<body>'
|
||||
echo '<nav>'
|
||||
echo '<a href="./index.html">index</a>'
|
||||
echo '<a href="./host.html">host options</a>'
|
||||
echo '<a href="./agent.html">agent options</a>'
|
||||
echo '</nav>'
|
||||
echo '<main>'
|
||||
echo '<h1>${title}</h1>'
|
||||
echo '<p><em>Auto-generated from the hyperhive flake. Source: <a href="${forgeRoot}/nix/docs/default.nix">nix/docs/default.nix</a>.</em></p>'
|
||||
cmark-gfm ${doc.optionsCommonMark}
|
||||
echo '</main>'
|
||||
echo '<footer>'
|
||||
echo '<p>hyperhive · <a href="${forgeRoot}">source</a></p>'
|
||||
echo '</footer>'
|
||||
echo '</body>'
|
||||
echo '</html>'
|
||||
} > $out
|
||||
'';
|
||||
Auto-generated from the hyperhive flake. Two reading paths:
|
||||
|
||||
# Landing page — same template shape, hand-authored intro + cross-links.
|
||||
indexHTML = pkgs.runCommand "hyperhive-docs-index.html" { } ''
|
||||
{
|
||||
echo '<!doctype html>'
|
||||
echo '<html lang="en">'
|
||||
echo '<head>'
|
||||
echo '<meta charset="utf-8">'
|
||||
echo '<meta name="viewport" content="width=device-width, initial-scale=1">'
|
||||
echo '<title>hyperhive — nix options reference</title>'
|
||||
echo '<style>'
|
||||
cat ${pkgs.writeText "hyperhive-docs-style.css" styleCSS}
|
||||
echo '</style>'
|
||||
echo '</head>'
|
||||
echo '<body>'
|
||||
echo '<nav>'
|
||||
echo '<a href="./index.html">index</a>'
|
||||
echo '<a href="./host.html">host options</a>'
|
||||
echo '<a href="./agent.html">agent options</a>'
|
||||
echo '</nav>'
|
||||
echo '<main>'
|
||||
echo '<h1>hyperhive — nix options reference</h1>'
|
||||
echo '<p>Auto-generated from the <a href="${forgeRoot}">hyperhive flake</a>. Two reading paths:</p>'
|
||||
echo '<h3><a href="./host.html">host options</a></h3>'
|
||||
echo '<p>Options exposed by <code>hyperhive.nixosModules.default</code> to operator host configurations: <code>services.hyperhive.{enable,domain,c0re,forge,matrix,gateway}.*</code>.</p>'
|
||||
echo '<h3><a href="./agent.html">agent options</a></h3>'
|
||||
echo '<p>Per-agent options declared in <code>nix/templates/harness-base.nix</code> and visible from every <code>agent.nix</code>: <code>hyperhive.model</code>, <code>hyperhive.allowedRecipients</code>, <code>hyperhive.extraMcpServers</code>, <code>hyperhive.frontend.*</code>, <code>hyperhive.forge.*</code>, <code>hyperhive.matrix.*</code>, <code>hyperhive.gui.*</code>.</p>'
|
||||
echo '<h3>Regenerate</h3>'
|
||||
echo '<pre><code>nix build .#docs # bundled static site (index + host + agent)'
|
||||
echo 'nix build .#docs-host # host page only (HTML)'
|
||||
echo 'nix build .#docs-agent # agent page only (HTML)</code></pre>'
|
||||
echo '<p>The bundle also ships <code>.md</code> versions of each page (<code>host.md</code>, <code>agent.md</code>) — same content, source-of-truth shape — alongside the HTML.</p>'
|
||||
echo '</main>'
|
||||
echo '<footer>'
|
||||
echo '<p>hyperhive · <a href="${forgeRoot}">source</a></p>'
|
||||
echo '</footer>'
|
||||
echo '</body>'
|
||||
echo '</html>'
|
||||
} > $out
|
||||
- [host options](host.md) — options exposed by
|
||||
`hyperhive.nixosModules.default` to operator host configurations
|
||||
(`services.hyperhive.{enable,domain,c0re,forge,matrix,gateway}.*`).
|
||||
- [per-agent options](agent.md) — options declared in
|
||||
`nix/templates/harness-base.nix`, visible from every `agent.nix`
|
||||
(`hyperhive.model`, `hyperhive.allowedRecipients`,
|
||||
`hyperhive.extraMcpServers`, `hyperhive.frontend.*`,
|
||||
`hyperhive.forge.*`, `hyperhive.matrix.*`, `hyperhive.gui.*`).
|
||||
|
||||
Regenerate with `nix build .#docs` (bundle), `.#docs-host`, or
|
||||
`.#docs-agent`.
|
||||
'';
|
||||
|
||||
hostHTML = mkHtmlPage "docs-host" "hyperhive — host options" hostDoc;
|
||||
agentHTML = mkHtmlPage "docs-agent" "hyperhive — per-agent options" agentDoc;
|
||||
hostMD = mkMarkdownPage "docs-host" "hyperhive — host options" hostDoc;
|
||||
agentMD = mkMarkdownPage "docs-agent" "hyperhive — per-agent options" agentDoc;
|
||||
in
|
||||
{
|
||||
host = hostHTML;
|
||||
agent = agentHTML;
|
||||
host = hostMD;
|
||||
agent = agentMD;
|
||||
|
||||
# Bundled static site nginx serves at `/options/`. Asset paths are
|
||||
# all relative so the prefix can change without rebuild.
|
||||
# Bundle of the option reference as markdown. The website renders
|
||||
# these `.md` to themed HTML for `/options/`; standalone consumers
|
||||
# get the CommonMark source directly.
|
||||
bundle = pkgs.runCommand "hyperhive-options-docs" { } ''
|
||||
mkdir -p $out
|
||||
cp ${indexHTML} $out/index.html
|
||||
cp ${hostHTML} $out/host.html
|
||||
cp ${agentHTML} $out/agent.html
|
||||
cp ${indexMD} $out/index.md
|
||||
cp ${hostMD} $out/host.md
|
||||
cp ${agentMD} $out/agent.md
|
||||
'';
|
||||
|
|
|
|||
Loading…
Reference in a new issue