docs/: authoring conventions

August 14, 2026 · View on GitHub

This tree is the source of truth for the gwm user docs and the future static documentation site. It is structured to drop straight into Nuxt Content (or any SSG that follows the same numeric-prefix routing convention).

layout

docs/
├── index.md                              # → /
├── 1.getting-started/                    # → /getting-started
│   ├── index.md
│   ├── 1.install.md                      # → /getting-started/install
│   ├── 2.first-worktree.md
│   └── 3.shell-init.md
├── 2.tui/                                # → /tui
├── 3.cli/                                # → /cli
├── 4.configuration/                      # → /configuration
├── 5.integrations/                       # → /integrations
├── 6.development/                        # → /development
└── 7.roadmap.md                          # → /roadmap

Numeric prefixes (1., 2., 3.) drive sidebar ordering in Nuxt Content and are stripped from the resulting URL. Add a new page anywhere in the tree by giving it the next free prefix in its parent folder.

frontmatter contract

Every page (including section index.md files) carries this minimal frontmatter:

---
title: <page title — rendered as <h1> and in <title>>
description: <one-sentence teaser, used for SEO and search>
---

Both fields reach the published site verbatim, as the <title> and the <meta name="description"> of the page. Nothing in the build reads them, so a defect there ships green and is only visible in a search result. Two rules on description, pinned by tests/docs_frontmatter_tests.rs:

  • 250 characters at most. Past that, no variant of the sentence comes out of a search result cut intact, so lead with the current state and drop the history.
  • Distinct from every other page of the same locale. Two URLs saying the same sentence compete for one snippet, and an engine drops or rewrites one of them. Section index.md files are where this happens: describe the section, not the page it links to.

Titles read in sentence case (First worktree, Shell completions), with proper nouns kept as they are spelled (GitHub issue / PR linking, gwm doctor). This one is on the author, not on a test.

Optional fields:

  • navigation.title: short label for the sidebar when the full title is too long.
  • navigation.icon: Iconify name (e.g. lucide:terminal) for SSGs that render section icons.
  • navigation: false: hide the page from the auto-generated sidebar (use for this README only).

Use repo-relative paths from this docs/ root so the same links resolve on GitHub and inside the future site:

See [Configurable launchers](/tui/launchers) for the `[git_tui]` / `[review]` schema.

(Nuxt Content rewrites bare /segment paths against the content root; on GitHub they render as broken-but-readable cross-references, acceptable until the site is live, at which point a relative-link audit can lift them all in one pass.)

images & assets

When pages need screenshots or diagrams, drop them under docs/<section>/_assets/ and reference them with a relative path (![keymap](./_assets/tui-keymap.png)). Keep this README out of the generated sidebar via navigation: false.

see also