configref

Overview ¶

Command configref regenerates the tables of the configuration reference page (website/content/reference/configuration.md) from internal/config, so the page lists every key, variable and default the loaders actually have (#1570).

The page stays hand-written prose around generated blocks. A block is the text between a begin marker and an end marker:

<!-- BEGIN GENERATED configref settings server. !server.cors. -->
...
<!-- END GENERATED configref -->

and its body is replaced on every run. The marker names what goes inside:

• settings PATTERN...: one row per server setting whose key matches a pattern. "a.b." matches every key under a.b, "a.b" matches that key, and a leading "!" excludes. Every server setting must land in exactly one block.
• env GROUP: the variables of that group in settings.yaml's environment list.
• cli: the developer CLI's config keys (~/.dexaflow/config.yaml).

Names, types and defaults come from the structs and default maps the loaders use (config.ServerSettings, config.CLISettings). The purpose of a key comes from settings.yaml when it has an entry there, and otherwise from the first paragraph of the Go field's doc comment.

Usage, from the repository root:

go run ./internal/tools/configref          # rewrite the page
go run ./internal/tools/configref -check   # fail when the page is stale