Skip to content

docs(site): regroup the sidebar and check the reference against the Rust build - #36

Merged
NaNIsaac merged 2 commits into
mainfrom
docs/structure
Oct 23, 2026
Merged

NaNIsaac merged 2 commits into
mainfrom
docs/structure

Conversation

@NaNIsaac

@NaNIsaac NaNIsaac commented Oct 22, 2026 •

Copy link
Copy Markdown
Owner

Tier: low

  • Sidebar and top navigation: groups become Getting Started, Guides, Reference, Project (en and ko). No page is added, moved or renamed; URLs stay the same.
  • site/scripts/check_reference.py can also check the reference against the Rust build (--rust-json docs/cli-matrix.json, the matrix from docs: generate a matrix of commands and options in each build #35).
  • No change to the CLI, README or page text.

Stacked on #34 (base docs/home-redesign).

Changes

  • Getting Started: Installation, then Quick Start (the existing getting-started page).
  • Guides: Recipes with three entries that open its sections (sharing code with an AI, working with changes, debugging a failed command), and MCP Integration. The Korean headings already carry the same ASCII ids (docs(site): terminal demo, workflows and security on the homepage #34).
  • Reference: Command Reference, Configuration, Output Formats, Terminal Capture.
  • Project: Security, Architecture, Rust and Python Builds (the rust-port page), Contributing.
  • Top navigation: Getting Started, Guides, Reference, Security, More; each item stays active on its group's pages.
  • No "Understanding a codebase" guide: there is no page for it yet, and the digest workflow is already in the sharing recipe.

Checked against the CLI

  • Option tables are checked against the Python build as before. Options only the binary has are documented under a heading of their own (today only #### --raw, only in the binary under cdg term). The check now reads those headings, and with --rust-json compares the tables plus those headings with the "rust" key of docs/cli-matrix.json (generated from clap in docs: generate a matrix of commands and options in each build #35, hidden options included).
  • uv run python site/scripts/check_reference.py --rust-json docs/cli-matrix.json with the matrix from docs: generate a matrix of commands and options in each build #35: "reference matches the CLI: 21 commands, 107 options; Rust build: 108 options". Without the flag: "21 commands, 107 options", as before.
  • Negative tests: deleting the --raw heading fails with "option --raw of the Rust build is not documented"; adding --raw to the Korean table fails with "documents --raw, which the Python build does not have".
  • The other difference in the matrix, -V for the version only in Rust, is a root option and outside the per-command tables.
  • Once docs: generate a matrix of commands and options in each build #35 is on main, add --rust-json docs/cli-matrix.json to the check step in docs.yml. It is not wired here, so this PR does not depend on docs: generate a matrix of commands and options in each build #35.
  • ruff check and ruff format --check pass.

Validation

  • npm run build passes; internal links: one known broken anchor, fixed by fix(site): link the Korean install section by an ASCII id #32.
  • Headless Chromium on recipes (en and ko with section anchors), commands, ko/mcp, rust-port, installation: the active sidebar entry follows the URL hash, the nav group is active, no console errors.

Screenshots

Before After

…project

Installation comes before the quick start, the recipes page gets entries for
sharing code, working with changes and debugging a failed command, MCP moves
to guides and security to project. No pages are added or moved.
With --rust-json docs/cli-matrix.json the check compares the option tables
plus the binary-only headings (#### `--raw`, only in the binary) with the
Rust build, and flags a binary-only option the Python build also has.
@NaNIsaac NaNIsaac changed the title docs(site): group the sidebar as getting started, guides, reference, project docs(site): regroup the sidebar and check the reference against the Rust build Oct 22, 2026
@NaNIsaac
NaNIsaac changed the base branch from docs/home-redesign to main October 23, 2026 06:39
@NaNIsaac
NaNIsaac merged commit 3313aec into main Oct 23, 2026
5 checks passed
@NaNIsaac
NaNIsaac deleted the docs/structure branch October 23, 2026 15:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant