docsgen

Overview ¶

Command docsgen renders the Seamless documentation site: markdown authored in docs-src/ becomes static HTML committed under docs/docs/, served by the same GitHub Pages config as the landing page (thereisnospoon.org/docs/).

The generated tree is committed, not built in CI, so `make docs-check` can prove the checked-in output matches the sources. That only works if rendering is deterministic: no timestamps, no map iteration order, no concurrency. See determinism_test.go, which renders twice and demands byte-equal output.

docsgen -src docs-src -out docs/docs      # regenerate (what `make docs` runs)
docsgen -serve 127.0.0.1:8899             # regenerate, then serve docs/ locally

Every page is written twice: index.html, and a markdown twin at index.md holding the page's full source markdown (see twin.go); the site root gets an index.md too (the llms.txt outline). The twins exist for `Accept: text/markdown` content negotiation -- a Cloudflare Transform Rule on the zone rewrites markdown-accepting requests for negotiable directory URLs to their index.md; browsers keep getting the HTML. SITE.md documents the rule.

Besides the docs tree, every run refreshes the crawler files at the site root (-site, default docs/): sitemap.xml, naming the landing page and every docs page; robots.txt, which points crawlers at it; and llms.txt / llms-full.txt, the site's nav and full source markdown for LLM consumers. All are committed and gated by `make docs-check`, so none can go stale against the nav.

Two pages are generated rather than authored, via a `generate:` key in their frontmatter (see generators.go): the MCP tool reference reads mcp.Catalog(), and the configuration reference reflects over config.Defaults(). Both derive from the code they document, so neither can drift from it silently.

The /scenarios/ pages: one crawlable, answer-first page per landing-page terminal scene. The transcripts come from scenes.js (loadScenes) -- never re-typed -- and the framing prose (the answer-first opener, the memory file that made the difference, how to reproduce) is authored per page in docs-src/_scenarios/<slug>.md. The underscore prefix keeps those files out of the docs nav (they are not docs pages; they publish at the site root), and this generator is what turns the pair into docs/scenarios/<slug>/index.html.