docs: Publish the command reference to GitHub Pages - #100
Conversation
The CLI's help text is the only complete description of its 61 commands, and it was only readable from a terminal. Render it as a website so it is linkable, searchable, and indexed. The site is nothing but the reference. Installing and getting started are already documented in the README and on docs.flagsmith.com, and a third copy here would be the one that goes stale — so the root command's own page is the home page and there is no hand-written prose anywhere on the site. Install and Guides are navbar links out to those two. cmd/docgen renders each page with cobra's markdown generator, so a page cannot drift from the binary: nothing about a command is written by hand. It walks the tree itself rather than using cobra's GenMarkdownTree, because that flattens every page into one directory — which gives a sidebar listing six commands all called "create", and URLs like /flagsmith_feature_variant_create/. Mirroring the command tree as a directory tree instead gives /feature/variant/create/ and navigation that nests the way the CLI does. Cross-references are rewritten relative to the page holding them, so they survive the /flagsmith-cli/ prefix a project site is served under. Hidden commands and hidden flags are skipped by cobra. The auto-generated date footer is disabled so the build is reproducible, and cobra's opening heading is dropped because the theme already renders the title. Only the newest release is published — GitHub Pages serves one artifact, and versioned docs would be machinery serving nobody while a single line is supported. But which release that is has to be visible, or a page found in a search result looks current to someone running an older CLI. A badge beside the navbar title names it where nobody has to scroll for it, and the footer repeats it with the context that explains it. The version is a literal in hugo.yaml that release-please bumps like the ones in install.sh and the README, so a local preview shows exactly what a deploy would and the workflow needs no step of its own to work it out. website/ therefore holds the Hugo config and three small templates: two are theme overrides Hextra gives no hook for — the navbar badge, and a home page that keeps its sidebar rather than hiding it — and one is Hextra's own footer extension point. Its go.mod is deliberately separate so the theme never becomes a dependency of the released binary. Docs deploy from release tags, so the published reference always describes a version you can install. A cheap generate-only job runs on pull requests to catch a broken generator before a release rather than during one. Importing cobra/doc adds three indirect dependencies (go-md2man, blackfriday, yaml/v3); they are build-time only for docgen and are not linked into the CLI.
Point installs at get.flagsmith.com rather than a raw.githubusercontent.com path, add the npm package, and open with what the CLI is for instead of calling it a work in progress. The pinned --version example is wrapped in release-please block markers so it bumps with every release like the ones in install.sh and install.ps1. It needs the block form rather than an inline annotation because the line sits inside a fenced code block, where the comment would render as part of the snippet.
|
Warning Review limit reached
Next review available in: 51 minutes Limit details: You’ve used the included review currently available. You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository. How can I continue?Wait for the limit to reset, then comment An organization admin can change what happens after included review limits in Billing. How do review limits work?CodeRabbit enforces per-developer PR review limits within each organization. For paid Pro and Pro+ reviews, CodeRabbit uses a developer's included PR review attempts over the past 7 days to set the current hourly allowance. At typical activity levels, the full plan allowance applies. Higher sustained activity can lower the allowance until earlier attempts leave the 7-day window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Plus Run ID: 📒 Files selected for processing (1)
📝 WalkthroughWalkthroughThe change adds a Cobra-based command reference generator and exposes the prepared command tree through Estimated code review effort: 4 (Complex) | ~45 minutes Merge Risk: 🟠 High · up to The PR adds documentation publishing that may fail during deployment because the build job lacks required Pages permissions, and it presents installation commands that execute mutable remote scripts, creating a concrete supply-chain security risk. These issues should be fixed before merging. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 91881893-b456-4257-a096-33859c29f395
⛔ Files ignored due to path filters (2)
go.sumis excluded by!**/*.sumwebsite/go.sumis excluded by!**/*.sum
📒 Files selected for processing (14)
.github/workflows/docs.yml.github/workflows/pull-request.yml.gitignoreREADME.mdcmd/docgen/main.gogo.modinternal/cmd/root.gorelease-please-config.jsonwebsite/README.mdwebsite/go.modwebsite/hugo.yamlwebsite/layouts/_partials/custom/footer.htmlwebsite/layouts/_partials/navbar-title.htmlwebsite/layouts/home.html
Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.
actions/configure-pages reads the site's base URL from the Pages API on every run, so with only contents: read the build job would have failed a tagged deployment with "Resource not accessible by integration". Read is all it needs: the action's enablement input defaults to false in v6, so it never tries to create the site — Pages still has to be pointed at Actions by hand. Deployment keeps pages: write.
1 participant
In this PR, we