Contributing to the Docs

The docs are two layers: hand-authored guides and generated reference. Guides you write; reference is produced from source and guarded by pnpm check:docs-code-owned.

Where things live

The standalone docs app renders this content from apps/docs/src/routes/docs/. The web app also renders it from apps/web/src/routes/docs/ at /docs.

Add or edit a guide

Create a Markdown file under apps/docs/content/ with frontmatter:

---
title: My Page
description: One line shown in search and nav.
section: Guides
order: 90
---

# My Page

It appears in the sidebar automatically (the nav is scanned from the folder).

[!TIP] Quote any frontmatter value that starts with a special character, for example title: "@scope/thing", or the YAML will not parse.

Section icons

A section's sidebar icon comes from the lowest-order page in that section which declares one, so only one page per section needs to set it:

---
title: Getting Started
section: Start
icon: rocket
order: 10
---

Available names are book, code, compass, flask, library, map, package, rocket, settings, shapes, terminal, and wrench. Anything unset falls back to book.

Sections with more than 12 pages start collapsed unless you are on one of their pages, which keeps the large Reference section from burying the rest.

Rich features you can use

Authored in plain Markdown, rendered by docs-engine:

• Callouts: > [!NOTE], > [!TIP], > [!WARNING], and the other GitHub/Obsidian callout markers.
• Mermaid: a ```mermaid fenced block (diagrams render as SVG)
• Code tabs, file trees, collapsible sections, and an on-page table of contents via a ## TOC marker.
• Math: inline $a^2 + b^2 = c^2$ and block $$...$$ equations.
• Code metadata: title="...", {2-4}, showLineNumbers, and diff fences.

Keep screenshot blocks and optimized images out of authored docs until their asset generation, storage, and refresh policy is code-owned. Use docs-engine's own package docs when you need its current renderer surface.

Refresh the generated reference

Reference is built from Code Atlas (Rust public surface), ts-morph (full TS surface plus JSDoc), and switchboard-api's openapi.json. Generated reference files are ignored by git and refreshed by docs:reference, docs:dev, and docs:build. CI validates that generation still succeeds and source-owned facts still line up. Current source inputs, docs workflow scripts, CI steps, pre-commit commands, and lint-staged patterns are generated locally in reference/operations.md.

Rust reference pages build and use the checked-out Code Atlas source. CODEATLAS_BINARY_PATH may select another executable. When that executable is unavailable or fails, docs:reference reports those Rust targets as skipped and still checks the generated TypeScript, OpenAPI, package, operations, dependency graph, and glossary pages.

Keep changes scoped

Docs commits should make their ownership obvious from the touched paths. Current script names and CI hook commands are generated in reference/operations.md.

Do not stage generated reference output. Keep source changes scoped so review stays focused: copy review for guides, generator review for reference behavior, and runtime review for route or docs-engine changes.

Verify before you commit

Use the generated command inventory in Operational Reference. Preview while writing, then smoke the real /docs route when the change touches docs rendering, route generation, docs-engine imports, or branch-host behavior. That smoke catches the failures the standalone preview cannot see: hydration errors, missing optimized client deps, and router-only 500s.

CI rejects code-owned docs generation failures and broken docs links. The generated Operational Reference lists the source-owned workflow facts. Run the strict generated-reference script when public source comments changed so generated pages keep source-backed summaries. Local signoff should include the route smoke for any docs change that can affect the web app.