Local Link Docs — Websites: Documentation Navigation

The documentation writer maintains README indexes from the pages beneath them, so readers can follow links from the repository's root without opening a file browser.

Generate the reading tree

Run the writer from the Cargo workspace, selecting the directory whose README starts the reading tree. It updates indexes in existing READMEs and creates no new pages or website routes.

cargo run -p link-docs-check --bin docs-tree -- --root . --write

Choose a root

--root selects a directory and defaults to the current directory. Use a workspace root to update its documentation, or a checkout root to update several workspaces together. Each index links only to its own descendants, so one workspace's index never acquires links into a sibling workspace.

Check without writing

--check is the default mode. It fails for a stale index or a document with no reading path from the selected root's README.md. The regular documentation tests run these same checks for their workspace.

cargo run -p link-docs-check --bin docs-tree -- --root . --check

Discover documents

The reading tree includes Markdown pages and README hubs under the selected root, including English documentation, references and planning notes. Each page belongs to its nearest existing README ancestor; a README belongs to the next README above it. Bridge folders without a README are traversed directly.

Excluded inputs

Source folders, a package's test and example folders, fixtures, assets, hidden infrastructure, internal agent instructions and website configuration are not reading-tree pages. Within a Cargo package, only README hubs and its own docs/ tree are documentation; Markdown elsewhere, such as command templates or prompts, is implementation data. Translations under docs/ are excluded; English pages provide the source tree. Build output and dependency folders are already excluded by the documentation checks' file reader.

Render indexes

Each entry takes the child's title and opening sentence; a package hub uses its Cargo description. The shared outline determines reading order; unmatched entries use stable path ordering. Descriptions are shortened for scanning, and inline code keeps its formatting. Changing a child's title, description, placement or location makes the corresponding generated navigation stale.

Preserve authored content

The writer owns the section between  and , including its ## Docs heading. On later runs, only that section changes. The generated Docs heading leads directly into its links, without a repeated introductory sentence. The opening, quickstart, other sections and code entry points remain authored content. Malformed or repeated markers stop the writer before it writes any index.

Migrate an existing index

On the first run, an existing ## Docs section becomes a marked index. Its ordinary links to discovered children are replaced by generated entries; editorial prose and links elsewhere remain. Without that section, the writer inserts one before ## Code, or at the end. Review the migration diff before committing, particularly pages that use tables or custom index formatting.

Keep the checks meaningful

Generated navigation has its own freshness check. Its lines and heading do not consume the authored line and heading budgets, while its links and prose remain checked. A generated block cannot hide arbitrary text: any content differing from the writer's expected output fails the freshness check.

Review grouping folders

The documentation checks warn about a code grouping folder that adds a README level around one child and has no documentation of its own. This is a review prompt rather than a failure: architectural layers, package roots and documentation bridge folders can have a purpose even when they contain one item. The writer never flattens folders.

One shared outline

Each website's docs/en/navigation.md contains its named outline under ## Pages. The website and README indexes consume this same order; page titles and descriptions remain in their owning documents. Locale URL mappings are structural metadata, while interface labels live in shared localization catalogs.

Curate placement

Move an entry in the outline to change its reading position. Regeneration preserves existing order and nesting. A README's child hub takes the position of its first ranked descendant; repository-only entries without a position in the public outline remain alphabetical.

Add documentation

The writer discovers new genuine pages and inserts them beneath their nearest existing parent in the outline. New root entries are appended in deterministic order. Run it after generating documentation so every new page has a persisted reading position, then review the placement. Missing or duplicate entries and stale indexes fail the checks.