Context
Documentation source moved from Zudoku (docs/pages/**/*.mdx) to Markdoc under docs/content/**/*.mdoc, with self-hosted configuration documented at docs/content/self-hosting/configuration.mdoc.
Current state of configdocsgen
cmd/configdocsgen reflects internal/config and injects generated environment variable and YAML example blocks into a target file between MDX-style placeholders ({/* BEGIN AUTOGENERATED ... */}).- Defaults still point at the removed path
docs/pages/references/configuration.mdx (see internal/config/config.go //go:generate and make docs/generate/config).
- The new
configuration.mdoc is hand-curated (sectioned tables, different column layout, short YAML snippet). It does not contain autogen placeholders and is not the same shape as the generator output (one large table + full generated YAML).
Questions for the team
- Do we still want a generated config reference, or is manual
configuration.mdoc enough?
- If we keep generation, should we:
- repoint the tool to
.mdoc and use Markdoc-safe placeholders (e.g. HTML comments instead of {/* ... */})?
- emit a separate generated page (e.g. full env var matrix) and link it from the curated configuration page?
- invest in grouped output to match the current section structure?
- If we retire the generator: remove
//go:generate, Makefile target, and cmd/configdocsgen, or leave a short note in contributing/ so the decision is documented.
Related
contributing/.plans/2025-05-26-config-documentation-synchronization.md (original plan; pre-refactor paths).
Opened to decide policy after the docs layout change; no code change required to close this—just a team decision and follow-up issues if needed.
Context
Documentation source moved from Zudoku (
docs/pages/**/*.mdx) to Markdoc underdocs/content/**/*.mdoc, with self-hosted configuration documented atdocs/content/self-hosting/configuration.mdoc.Current state of
configdocsgencmd/configdocsgenreflectsinternal/configand injects generated environment variable and YAML example blocks into a target file between MDX-style placeholders ({/* BEGIN AUTOGENERATED ... */}).docs/pages/references/configuration.mdx(seeinternal/config/config.go//go:generateandmake docs/generate/config).configuration.mdocis hand-curated (sectioned tables, different column layout, short YAML snippet). It does not contain autogen placeholders and is not the same shape as the generator output (one large table + full generated YAML).Questions for the team
configuration.mdocenough?.mdocand use Markdoc-safe placeholders (e.g. HTML comments instead of{/* ... */})?//go:generate, Makefile target, andcmd/configdocsgen, or leave a short note incontributing/so the decision is documented.Related
contributing/.plans/2025-05-26-config-documentation-synchronization.md(original plan; pre-refactor paths).Opened to decide policy after the docs layout change; no code change required to close this—just a team decision and follow-up issues if needed.