Writing guide
Conventions for writing and changing pages on this site. The site is Docusaurus 3.10 (@docusaurus/core 3.10.2) with
@docusaurus/theme-mermaid and local search, in website/. It is not part of the pnpm workspace and has its own
lockfile.
Where things live
| Path | Purpose |
|---|---|
website/docusaurus.config.js | Site config. routeBasePath: '/', onBrokenLinks: 'throw', onBrokenAnchors: 'throw', markdown.mermaid: true, onBrokenMarkdownLinks: 'throw' |
website/sidebars.js | One sidebar main: intro, then one autogenerated category per folder |
website/docs/intro.md | Landing page, slug / |
website/docs/<section>/ | architecture, runtime, security, factory, quality, operations, reference; each has _category_.json |
website/scripts/check-diagrams.mjs | Mermaid validator (pnpm run check:diagrams) |
Because routeBasePath is /, a file docs/security/gateway.md is served at /security/gateway.
Front matter
Every page starts with front matter that has title and sidebar_position:
---
title: Gateway
sidebar_position: 3
---
- The section overview is
overview.mdwithsidebar_position: 1; other pages use 2, 3, and so on in reading order. slugis set only where the route differs from the path:intro.mdusesslug: /, the glossary/glossary, the decisions page/decisions(the navbar links to those two).- Start the body with a
#heading matching the title, then one paragraph saying what the page covers.
Content rules
- Write from the code and docs, not from memory. Read the real source:
apps/*,packages/*,docs/*.md, the ADRs underdocs/sessions/*/adr,scripts/,CODING_STANDARDS.md,GLOSSARY.md. - Code wins. When a doc and the code disagree, describe the code and note the discrepancy.
- Mark status honestly. Use "Not built" and "Unverified" as the source docs do. Never present a plan as built.
- Be exact. Give env vars with defaults, routes, status codes, error codes, table and column names, queue names, constants and limits with their values.
- Prefer structure. Tables for limits, env vars and error codes; diagrams for flows and lifecycles; short paragraphs between them.
The Sources section
Every page ends with ## Sources: a bullet list of repository paths the page was written from, optionally with symbol
names:
## Sources
- `packages/agent-types/src/http.ts` (`HTTP_STATUS`, `toResponse`)
- `apps/api/src/errors.ts` (`sendOutcome`)
- `docs/p2-findings.md`
Repository files are always plain code spans, never links (the site cannot resolve them and broken links fail the build).
Links between pages
- Use absolute site paths without the file extension:
[the gateway](/security/gateway). - Only link to pages that exist;
onBrokenLinks: 'throw'fails the build otherwise. - An anchor link (
/architecture/configuration#refused-variables) must match a real heading;onBrokenAnchorsalso throws. Anchors are the heading text lowercased with spaces as hyphens.
MDX pitfalls
Docs are parsed as MDX. Outside code fences and inline code:
| Character | Problem | Write instead |
|---|---|---|
< | starts a JSX tag | <, or put the expression in backticks |
{ and } | start a JSX expression | put the text in backticks |
| a pipe inside a table cell | splits the cell, even inside inline code | escape it with a backslash |
Inside inline code and code fences these characters are safe.
Mermaid conventions
Diagrams render in the browser with the mermaid version bundled by @docusaurus/theme-mermaid; the validator uses
mermaid 11.17.2.
| Content | Diagram type |
|---|---|
| Request or activity flows | sequenceDiagram |
| Lifecycles (job, run, session status) | stateDiagram-v2 |
| Tables and relations | erDiagram |
| Components and containers | flowchart with subgraph (C4 style) |
| Type families | classDiagram |
Rules that keep diagrams valid:
- Quote labels that contain parentheses, slashes, colons or other punctuation:
A["label (x)"]. - The only HTML allowed in labels is
<br/>. - Never use the bare word
endas a node id (it closes asubgraph); usedoneorfinish. - In
erDiagram, attribute types are single words (numeric, notnumeric(18,8)); put details in the quoted comment:numeric amount_usd "reservation". - Do not name hosts or addresses in diagrams; use roles and ports.
Example:
Validating diagrams
docusaurus build does not parse mermaid (rendering happens in the browser), so a syntax error only shows up for a
reader. Run the validator, which parses every mermaid block under docs/ with the real parser in jsdom:
cd website
pnpm run check:diagrams
It prints N mermaid blocks in M files, K invalid and one file:line: message per failure, and exits 1 when any block
is invalid. Fix every failure before committing.
No secrets, no host identities
Never paste into a page:
- secrets, tokens, API keys, key ids or private keys (including example values that look real; job tokens start with
afj_, so never write one followed by its hex body); Bearerheaders with values;- private IP addresses, tailnet addresses, real hostnames or domains of hosts.
Describe roles ("the core host", "the sandbox host", "a fleet host") and ports instead. Before committing, grep your page:
grep -nE '([0-9]{1,3}\.){3}[0-9]{1,3}|Bearer[[:space:]][A-Za-z0-9]|sk-ant|afj_[0-9a-f]' website/docs/<section>/<page>.md
Write no IPv4 literals at all, not even loopback or any-address values: say "the IPv4 loopback" or "the IPv4 any-address (all interfaces)" instead, so the grep stays clean.
Adding a page
- Pick the section folder and a short kebab-case file name; that becomes the URL.
- Add front matter with
titleand the nextsidebar_position. - Write the page from the sources, with tables and diagrams.
- End with
## Sources. - Link it from the section overview, and from other pages only by absolute site path.
- Run
pnpm run check:diagramsand the secrets grep above. - Run
pnpm buildinwebsite/to catch broken links and anchors (one build at a time; parallel builds share the output directory).
Sources
website/docusaurus.config.js,website/sidebars.js,website/package.jsonwebsite/scripts/check-diagrams.mjswebsite/docs/intro.md,website/docs/*/_category_.jsonCODING_STANDARDS.mdsection 5 (comments and documentation)