Documentation
¶
Overview ¶
Command gen-config-reference renders the public Configuration reference page (website/docs/reference/configuration.md) from the configuration key registry (docs/reference/CONFIG_KEY_REGISTRY.md).
The registry is the internal source of truth for every configuration key: defaults, lifecycle tags, and semantics. The public site must not link to it (readers should not need the internal tree), so this generator projects the registry's per-section key tables into a Docusaurus page. CI keeps the two in lockstep: a freshness step regenerates the page and fails on any diff, so editing the registry without re-running the generator — or editing the generated page by hand — breaks the build.
What is emitted:
- A fixed intro (precedence chain, env-var mapping, lifecycle legend) maintained here, not parsed from the registry.
- Every `## Section` of the registry that contains at least one markdown table, with its `###`/`####` subheadings and tables. Free prose between tables is NOT carried over — it is written for maintainers and is full of internal references; the durable per-key content lives in the Notes column.
- A fixed note for the `modules.*` namespace (that registry section is all prose, but the namespace must not vanish from the public page).
Table cells are sanitized for the public site: parentheticals and clauses that reference internal artifacts (decision-record IDs, deprecation or migration tickets, internal file names, priority labels) are dropped. The generator then re-scans its own output and exits non-zero if any internal vocabulary survived, so a new kind of leak fails CI instead of shipping.
Usage: go run ./scripts/website/gen-config-reference [-root .]
Source Files