docs

Documentation

Overview

Package docs renders a Cobra command tree to byte-stable Markdown for the jira-cli documentation site. It mirrors the GitHub CLI's internal/docs generator: GenMarkdownTreeCustom walks the tree and GenMarkdownCustom renders one page per command, taking a filePrepender for site front-matter and a linkHandler for relative links between pages. Output is deterministic — no generation timestamp, stable ordering — so a CI drift gate only ever sees real changes.

Flags are rendered from clib's metadata (github.com/gechr/clib), not raw pflag, so the reference surfaces the same groups, authored placeholders, allowed values, aliases and negatable variants that the terminal help shows.

Index

• Constants
• func GenLLMsTxt(w io.Writer) error
• func GenMarkdownCustom(cmd *cobra.Command, w io.Writer, _, linkHandler func(string) string) error
• func GenMarkdownTreeCustom(cmd *cobra.Command, dir string, filePrepender, linkHandler func(string) string) (err error)
• func GenReferenceNav(root *cobra.Command, indent string) string
• func SpliceReferenceNav(config, navBlock string) (string, error)

Constants

const (
	ReferenceNavStartMarker = "# >>> gen-docs:reference-nav (generated — do not edit by hand)"
	ReferenceNavEndMarker   = "# <<< gen-docs:reference-nav"
)

Reference-nav markers delimit the machine-owned block in zensical.toml. Only the text between them is replaced by GenReferenceNav; the curated topic sections of the nav are left untouched.

Functions

func GenLLMsTxt

func GenLLMsTxt(w io.Writer) error

GenLLMsTxt writes a deterministic llms.txt: a short project summary, the conceptual page map, and a pointer to the canonical agent surface (the embedded runbook and schema), which are the source of truth for agents.

func GenMarkdownCustom

func GenMarkdownCustom(cmd *cobra.Command, w io.Writer, _, linkHandler func(string) string) error

GenMarkdownCustom renders a single command's page to w. linkHandler rewrites references to other generated pages; filePrepender is accepted for signature parity with the tree walker and is not used per-command.

func GenMarkdownTreeCustom

func GenMarkdownTreeCustom(cmd *cobra.Command, dir string, filePrepender, linkHandler func(string) string) (err error)

GenMarkdownTreeCustom walks cmd and every descendant, writing one Markdown page per command into dir as a nested directory tree: a command with subcommands becomes <path>/index.md, a leaf becomes <path>.md. The index.md naming is what lets Zensical treat the parent command as a clickable section index in the navigation (config.py _is_index recognizes index.md / README.md only). filePrepender receives the file path and returns front-matter to prepend; linkHandler rewrites a target page's relative path into a link. It is the entry point used by cmd/gen-docs.

func GenReferenceNav

func GenReferenceNav(root *cobra.Command, indent string) string

GenReferenceNav renders the zensical.toml nav element for the generated reference tree: a single `{ Reference = [ { "jira" = [...] } ] }` entry that mirrors the command tree. Paths come from docRelPath and children from availableSubcommands — the same helpers the page walker uses — so the nav can never disagree with the generated page filenames. indent is the leading whitespace for the element, matching the nav array's element indentation.

func SpliceReferenceNav

func SpliceReferenceNav(config, navBlock string) (string, error)

SpliceReferenceNav replaces the text between the reference-nav markers in config with navBlock, leaving everything else untouched. It errors if the markers are missing or out of order.