docs: Add a commands landing page

Brendan Lynchrequested to merge
8486-add-commands-landing-page into main

Description

The GitLab Docs navigation gives every entry a URL — there are no label-only grouping nodes — so grouping the 283 generated glab command entries under a Commands parent needs a real page at https://docs.gitlab.com/cli/commands/.

This is the third of four merge requests in #8486. It covers the commands landing page only.

Changes:

  • Add genCommandsPage to cmd/gen-docs/docs.go, which writes docs/source/commands.md with the list of top-level commands. The page is generated rather than hand-authored, so the list stays in sync with the command tree. It carries the generated marker, so pruneGeneratedPages rewrites it on every make gen-docs run.
  • Replace the ## Commands list in the generated root page with a pointer to the new page.
  • Turn printRootSubcommands into rootSubcommandList, which returns just the bullet list, so the root page and the landing page share one source for it. Links stay relative to docs/source/, so they resolve the same from either page.
  • Extract writeGeneratedHeader for the front matter and generated-by-a-script comment, which were duplicated across the two existing page generators and would have been a third time here. make gen-docs changes only _index.md out of the 288 generated files, which confirms the extraction is byte-identical for the rest.
  • Add tests covering the new page's contents (available commands listed, hidden and deprecated ones excluded) and the root page's pointer.

docs/navigation-glab.yaml is unchanged. genNav walks the cobra command tree only, so the new page never enters the generated navigation block — the Commands parent is added by hand in docs-gitlab-com, outside the glab-cli sentinels.

Not in this merge request

  • Configuration, connection, and proxy content. Blocked on !3602 (merged), which is still adding a custom HTTP headers section to the README.
  • Navigation entries in docs-gitlab-com. Those merge last, because check_menu_links.cjs fails on navigation URLs missing from the built sitemap and the build clones this project's main branch. The Commands entry can only be added once this merge request is on main.

Related issues and merge requests

Documentation

If this MR adds or updates CLI command documentation, follow the conventions in the GitLab CLI (glab) documentation style guide, run make gen-docs, and commit the updated files in docs/source/.

Merge request reports