generate-reference

Overview ¶

generate-reference generates REFERENCE.md (or other files) from Cobra command metadata.

It reads input file(s), finds GENERATE marker pairs, and replaces content between START and END with generated output. Structure is controlled by the input file.

Marker format:

• GENERATE_TOC:START ... GENERATE_END - table of contents
• GENERATE_GLOBAL_FLAGS:START ... GENERATE_END - global options
• GENERATE_HELP:path:START ... GENERATE_END - help output for command (e.g. path=connection)
• GENERATE:path1|path2|path3:START ... GENERATE_END - command docs (| separator)

Use <!-- GENERATE_END --> to close any block (no need to repeat the command list).

Usage:

go run ./tools/generate-reference --input REFERENCE.md                    # in-place
go run ./tools/generate-reference --input REFERENCE.template.md --output REFERENCE.md
go run ./tools/generate-reference --input a.mdoc --input b.mdoc           # batch, each in-place
go run ./tools/generate-reference --input REFERENCE.md --check            # verify up to date

For website two-column layout (section/div/aside), add --no-toc, --no-examples-heading, and wrappers:

--no-toc --no-examples-heading --wrapper-section-start "<section>" --wrapper-section-end "</section>"
--wrapper-main-start "<div>" --wrapper-main-end "</div>"
--wrapper-aside-start "<aside>" --wrapper-aside-end "</aside>"

For REFERENCE.md (no wrappers, include in-page TOC): use --no-wrappers or omit wrapper flags.