docs: publish plugin-env.md on the options-doc Pages site (#614)

[vibechoom]

Closes #614

Design points settled (per the issue)

1. Who renders the Markdown? Took the preferred option: the options-doc derivation now renders docs/plugin-env.md too, reusing the exact same rendering mechanism options.html uses (factored into a shared render_page shell function so both pages share one source of styling truth). The workflow (.github/workflows/options-doc.yml) stays a dumb copier — it just copies files out of result/.

   One tool swap was required to do this properly: cmark → cmark-gfm. plugin-env.md's env-var reference tables are GFM pipe tables (| Variable | Default | Effect |), which plain CommonMark has no syntax for — verified with plain cmark --unsafe first, which printed the | characters literally instead of a table. cmark-gfm --extension table is still the same tiny C library (no pandoc/Haskell closure), just the GFM-flavored build, applied uniformly to both docs (harmless on options.md, which has no tables).

2. The root page. index.html is no longer a byte-copy of options.html. The derivation now generates a small landing page linking both documents, styled consistently with the rest of the site (same inline CSS approach, no new dependency, no JS framework). Both options.html and plugin-env.html also gained a small "← trollshell docs" nav link back to the new root.

Review follow-up (this PR was adversarially reviewed before merge)

Four gaps were found and fixed in a second commit, three cosmetic-shaped but one structural:

1. options-doc is now in checks, not just packages. nix flake check — the only gate CI runs on PRs — never built the options-doc derivation this PR just made meaningfully bigger. That's the exact chore(ci): flake checks never build packages.trollshell — CI can be green while nix build is red #449-class gap flake.nix already documents for trollshell/trollshell-control-center: a broken derivation could stay green here and only surface as a red Pages deploy after merge.

   Wiring it in wasn't a plain inherit, though — options-doc was originally defined inline inside packages's own let block, and checks has its own, separately-scoped let block (each forAllSystems callback is an independent scope), so the binding simply wasn't reachable from there. Fixed by extracting the whole derivation into nix/options-doc.nix, pkgs.callPackage'd from both packages and checks — the same shape already used for trollshell, bundledPlugins, and hytte-infobroker, which are likewise built via a shared file from both outputs rather than defined inline in one and inherited by the other. options-doc is pure module evaluation plus one tiny C binary (cmark-gfm), so this is effectively free on every nix flake check run.

2. nix/module-common.nix's plugins.<name>.env option description — the only in-repo cross-reference to the env-knob doc — pointed at raw Markdown on GitHub instead of the newly-published plugin-env.html. Repointed to the absolute Pages URL: https://vibec0re.github.io/trollshell/plugin-env.html. Deliberately absolute, not relative — this same description is rendered by nixos-option and man home-configuration.nix, where a relative plugin-env.html link resolves to nothing.

3. Shared page styling. The landing page's inline <style> was a second, independently-drifting copy of render_page's (already visibly different: the landing page's <h1> inherited line-height:1.5 from body while both doc pages used 1.2). Folded into the nix/options-doc.nix extraction: page_style/page_head/page_foot are now one shared shell function/variable set used by all three generated pages — verified byte-identical <style> blocks across index.html, options.html, and plugin-env.html after the fix.

4. Workflow copy step now matches its own comment. options-doc.yml claimed "this workflow only copies files out of result/ into _site/" while actually hand-enumerating five cps — a sixth derivation output would have silently not published, with no gate catching it. Changed to cp -R result/share/doc/trollshell/. _site/, so the comment is now literally true and a future output file ships automatically.

Gate evidence

nix build .#options-doc, inspecting result/share/doc/trollshell/ (current, post-review-fixes):

$ ls -la result/share/doc/trollshell/
index.html        911 bytes   — landing page, links options.html + plugin-env.html, shares render_page's style
options.html    27011 bytes   — options reference, nav link back to index, shared style
options.md      21554 bytes   — unchanged raw nixosOptionsDoc CommonMark (description text grew slightly, see point 2)
plugin-env.html 14940 bytes   — rendered plugin-env.md; confirmed 5 real <table> elements (GFM pipe tables)
plugin-env.md   15778 bytes   — raw copy of docs/plugin-env.md

plugin-env.html has its own <h1>Plugin environment-variable reference</h1> (from the file's own top heading — no duplicate H1 injected, unlike options.md, which has none of its own and gets one injected via render_page's optional third argument).

nix fmt — first run: 0 changed. Second run: 0 changed.

nix flake check -L was kicked off locally to double-check the new checks entry doesn't turn CI red, but the workspace-wide clippy/test/VM suite runs well past any reasonable local wait (~37 min is this repo's own CI number for the equivalent job) — pushing was correctly prioritized over waiting on a local run that duplicates what CI's flake-check job will verify authoritatively. If options-doc-in-checks turns this PR's CI red, that is exactly the signal adding it was for, and it'll get fixed then.

What CI does and doesn't cover

options-doc.yml (the actual Pages-publishing workflow) is deliberately not part of nix flake check and still isn't after this PR — so CI never exercises the cp -R/deploy steps themselves, only the options-doc derivation's build (now via checks, see review point 1 above).

Manual check for a human after merge: watch the "options doc → GitHub Pages" Action run once this lands on main, then check the deployed site:

• Root (https://vibec0re.github.io/trollshell/) shows the small landing page (not the options doc directly) — confirm both links work.
• .../plugin-env.html renders with real tables, code spans, and the "← trollshell docs" nav back to root.
• .../options.html still renders correctly, including its plugins.<name>.env description now linking out to plugin-env.html with a real, working absolute URL.

🤖 Generated with Claude Code