Documentation
¶
Overview ¶
gen-docs-embed mirrors the canonical documentation pages listed in `docs-web/mkdocs.yml`'s `nav` into an embedded tree at `core/embedded_docs/` so the runtime's `//go:embed embedded_docs/*` directive picks them up. That embedded tree is what `rad docs` reads, which means `rad docs` always serves docs matching the installed binary's version - no network, no drift.
This is the third destination compiled from the same source set:
- the website (mkdocs reads docs-web/docs/ directly)
- llms.txt / llms-full.txt (docs-web/hooks/generate_llms_txt.py)
- rad docs (this generator)
The Python hook resolves titles/H2s/nav the same way for its table of contents, so those rules here (`_strip_front_matter`, `_resolve_title`, `_extract_h2s`, `_parse_nav`) intentionally mirror it. For the full page bodies, the hook now reads this generator's cleaned output (core/embedded_docs/) rather than re-cleaning the raw sources, so llms-full.txt and `rad docs all` are byte-for-byte the same content. The drift gate test in core/testing guards parity between the nav and the embedded tree.
Behaviour:
- Parses `nav`, keeping only the sections whose pages we embed (Guide, Reference, Examples) - the same set the Python hook inlines into llms-full.txt.
- For each page reads docs-web/docs/<path> (following the reference/syntax.md symlink to root SYNTAX.md, and reading the already-generated functions.md / errors.md), strips YAML front matter, resolves the title, and extracts H2s for the TOC.
- Normalizes the body through tools/docir: mkdocs-only markup (admonitions, content tabs, result <div>s, ragged GFM tables) and HTML-comment authoring notes don't survive a terminal renderer, so docir converts them to clean markdown that reads well both rendered in a TTY and piped raw into LLM context.
- Writes the normalized body to core/embedded_docs/<slug>.md and a manifest.json capturing ordered {slug, section, title, h2s}.
- Idempotent (no mtime bump when unchanged) and prunes stale slugs, like tools/gen-funcs-go.
Usage (defaults assume invocation from the repo root):
go run ./tools/gen-docs-embed
Source Files