## Problem The [`gitlab-org/cli`](https://gitlab.com/gitlab-org/cli) project auto-generates its command reference docs under `docs/source/` from each `cobra.Command`'s `Short`, `Long`, `Example`, and flag descriptions (via `cmd/gen-docs/docs.go`, run as `make gen-docs`). A pre-commit hook regenerates docs on changes to `internal/commands/**` and fails on drift, so the Markdown pages stay in sync with the code automatically. However, the [`data/en-us/navigation.yaml`](https://gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/-/blob/main/data/en-us/navigation.yaml) entries under `- title: GitLab CLI (glab)` (currently around line 3090) must be updated by hand in this repo every time a `glab` command or subcommand is added, renamed, or removed. This is easy to forget and the change lands in a separate MR from the one that introduces the command, so new pages can ship without a nav entry. ## Current navigation structure for glab ```yaml - title: GitLab CLI (glab) url: 'cli/' submenu: - title: glab alias url: 'cli/alias/' submenu: - title: glab alias delete url: 'cli/alias/delete/' - title: glab alias list url: 'cli/alias/list/' ... ``` Each entry maps 1:1 to the directory tree under `docs/source/` in `gitlab-org/cli`, so the data is already fully derivable from the cobra command tree. Existing drift caused by manual maintenance, for example: - `- title: check-update` is missing the `glab` prefix used by every other entry (line ~3129). ## Proposed automation options ### Option 1 (recommended) — Generate nav block in `gitlab-org/cli`, sync via CI 1. Extend `cmd/gen-docs/docs.go` (or add a sibling `cmd/gen-nav/`) in `gitlab-org/cli` to walk the cobra tree and emit the YAML submenu for the `GitLab CLI (glab)` section into a checked-in artifact (e.g. `docs/navigation.yaml`). 2. Add a `make gen-nav` target and wire it into the existing pre-commit/pre-push drift checks so the generated YAML stays in sync with cobra definitions. 3. A CI job (on merge to `main`, on release, or on a schedule) opens an MR against `docs-gitlab-com` that splices the generated block into `data/en-us/navigation.yaml` between sentinel comments, e.g.: ```yaml # BEGIN glab-cli (auto-generated, do not edit) ... # END glab-cli ``` The MR is idempotent (same branch name / title), so re-runs update the existing MR instead of creating duplicates. ### Option 2 — Sentinel markers + scheduled CI job, no committed artifact The CI job runs the generator, fetches `docs-gitlab-com`, replaces the block between sentinel markers, and opens an MR. Lighter on `gitlab-org/cli` but the generator output isn't reviewable in that repo's MRs. ### Option 3 — `docs-gitlab-com` includes an external YAML fragment `gitlab-org/cli` publishes the generated fragment (e.g. via a raw URL on `main` or a release artifact) and `docs-gitlab-com` pulls it in at build time. Cleanest long-term solution but requires tooling changes on the docs site. ## Related - Source repo: <https://gitlab.com/gitlab-org/cli> - Generator: [`cmd/gen-docs/docs.go`](https://gitlab.com/gitlab-org/cli/-/blob/main/cmd/gen-docs/docs.go) - Nav file: [`data/en-us/navigation.yaml`](https://gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/-/blob/main/data/en-us/navigation.yaml)