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

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.