Generate and Publish Command Reference Docs
Generate and Publish Command Reference Docs
Agent
Claude Code
Model
Claude Opus 4.6
Shared
Feb 16, 6:04 PM
Messages449
Implement the following plan:
The command reference on the website is manually maintained and covers about 18 topics, but the CLI has 64 commands. Many commands have no docs at all. The manual docs contain good narrative content (tutorials, CI examples, use cases) that shouldn't be replaced, so generated reference docs go in a separate section.
git-pkgs/git-pkgs)New file: scripts/generate-docs.go
Mirrors the existing scripts/generate-man.go. Imports cmd.NewRootCmd(), calls doc.GenMarkdownTreeCustom() to write one markdown file per command into a docs/ directory. The filePrepender callback injects Hugo frontmatter (title, weight) at the top of each file. The linkHandler callback rewrites Cobra's git-pkgs_vulns_blame.md links into relative Hugo paths. Sets DisableAutoGenTag = true on the root command to suppress the auto-generated timestamp footer (it creates noisy diffs on every run).
Add to .goreleaser.yaml hooks (alongside the man page generator):
git-pkgs/website)New file: .github/workflows/generate-docs.yml
Runs on a schedule (weekly) and on workflow_dispatch for manual runs. Steps:
git-pkgs/git-pkgs at latest taggo run scripts/generate-docs.go inside the cloned CLIdocs/ output into content/docs/reference/peter-evans/create-pull-requestNew file: content/docs/reference/_index.md
Section landing page with title "Command Reference" and a high weight (90) so it sorts near the bottom of the sidebar, after the narrative guides.
Edit: content/docs/_index.md
Add a card linking to the new reference section:
{{< card link="reference" title="Command Reference" subtitle="Every command and flag" >}}
Edit: hugo.yaml
Enable the llms.txt output format that hextra already supports:
go run scripts/generate-docs.go and inspect the docs/ output -- should produce ~64 markdown files with Hugo frontmattercontent/docs/reference/hugo server and check the sidebar shows the reference section with all commands/llms.txt is served and includes the reference pageshugo --minify to confirm a clean buildIf you need specific details from before exiting plan mode (like exact code snippets, error messages, or content you generated), read the full transcript at: /Users/andrew/.claude/projects/-Users-andrew-code-git-pkgs-website/e2798a3a-05ca-4e41-8eda-e9df79186723.jsonl
Let me start by exploring both repos to understand the existing structure.
Let me read the key files I need to reference directly.
Let me check what Cobra's markdown doc generation API looks like and understand the command naming pattern.
Now I have everything I need. Let me look at the root command quickly to understand DisableAutoGenTag.
Good. Now I have the full picture. Let me implement everything.
Those diagnostics are just gopls workspace warnings since the file is in a different repo from the current working directory. Not an issue.
Now let me check the pinned action versions used in existing workflows so I can match the style.
I need to look up the pinned SHA for actions/setup-go and peter-evans/create-pull-request. Let me check what versions are commonly used.
Now let me verify everything works. First, run the docs generator in the CLI repo.
73 files total. Some of those are pre-existing files (like bisect.md, ci-cd.md, notes.md, README.md etc. from an existing docs/ directory). Let me check what was already there.
The CLI repo already has a docs/ directory with hand-written files. I should write to a separate directory to avoid mixing. Let me fix the script.
Now update the workflow to match.
Now let me clean up the previously generated files in docs/ and regenerate into the right place.
64 files, exactly as expected. Let me verify the frontmatter and content of a couple files.
Frontmatter and links look correct. Now copy the generated files to the website and test the Hugo build.
65 files (64 generated + _index.md). Now test the Hugo build.
Build is clean. Let me check if llms.txt was generated and verify the reference pages are in the output.
All there. Let me verify the llms.txt content and that inter-command links work.
Reference pages are in llms.txt. Let me check that the inter-command links resolve correctly in the built HTML.
Lines are too long to see the actual links. Let me extract them more precisely.
Links are resolving correctly. The vulns page links to https://git-pkgs.dev/docs/reference/git-pkgs_vulns_blame/ and all its subcommands, and back up to the root git-pkgs page. Everything works.
Now let me clean up the generated files from the CLI repo (since they shouldn't be committed there) and the website's public directory.
Also remove the copied reference docs from the website's content dir (those will come from the workflow in practice).
Let me also make sure the CLI repo's docs/reference/ dir gets gitignored so generated output doesn't accidentally get committed there.
Let me start the hugo server. First I need to regenerate the reference docs so there's content to browse.
Hugo server is running at http://localhost:1313/. The reference section should be at http://localhost:1313/docs/reference/.
Here's a summary of everything that was done:
CLI repo (git-pkgs/git-pkgs):
scripts/generate-docs.go -- mirrors generate-man.go, uses doc.GenMarkdownTreeCustom() with Hugo frontmatter and ref shortcode linksgo run scripts/generate-docs.go to .goreleaser.yaml before hooksdocs/reference/ to .gitignoreWebsite repo (git-pkgs/website):
.github/workflows/generate-docs.yml -- weekly + manual, clones CLI at latest tag, generates docs, opens PR via peter-evans/create-pull-requestcontent/docs/reference/_index.md -- section landing page with weight 90content/docs/_index.mdoutputs.home with llms format to hugo.yamlVerified:
hugo --minify builds clean (106 pages)/llms.txt includes all reference pageslooking good, can we list the commands on http://localhost:1313/docs/reference/
Two things to fix: remove the redundant SEE ALSO sections (sidebar handles navigation), and add a command listing to the landing page. Let me handle both.
I'll replace the Cobra GenMarkdownTreeCustom call with a custom writer that skips the SEE ALSO section entirely (the sidebar handles navigation). I'll also create a shortcode for the landing page listing.
Now create the shortcode for listing commands on the landing page.