Skip to main content

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​

PathPurpose
website/docusaurus.config.jsSite config. routeBasePath: '/', onBrokenLinks: 'throw', onBrokenAnchors: 'throw', markdown.mermaid: true, onBrokenMarkdownLinks: 'throw'
website/sidebars.jsOne sidebar main: intro, then one autogenerated category per folder
website/docs/intro.mdLanding page, slug /
website/docs/<section>/architecture, runtime, security, factory, quality, operations, reference; each has _category_.json
website/scripts/check-diagrams.mjsMermaid 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.md with sidebar_position: 1; other pages use 2, 3, and so on in reading order.
  • slug is set only where the route differs from the path: intro.md uses slug: /, 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​

  1. Write from the code and docs, not from memory. Read the real source: apps/*, packages/*, docs/*.md, the ADRs under docs/sessions/*/adr, scripts/, CODING_STANDARDS.md, GLOSSARY.md.
  2. Code wins. When a doc and the code disagree, describe the code and note the discrepancy.
  3. Mark status honestly. Use "Not built" and "Unverified" as the source docs do. Never present a plan as built.
  4. Be exact. Give env vars with defaults, routes, status codes, error codes, table and column names, queue names, constants and limits with their values.
  5. 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).

  • 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; onBrokenAnchors also throws. Anchors are the heading text lowercased with spaces as hyphens.

MDX pitfalls​

Docs are parsed as MDX. Outside code fences and inline code:

CharacterProblemWrite instead
<starts a JSX tag&lt;, or put the expression in backticks
{ and }start a JSX expressionput the text in backticks
a pipe inside a table cellsplits the cell, even inside inline codeescape 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.

ContentDiagram type
Request or activity flowssequenceDiagram
Lifecycles (job, run, session status)stateDiagram-v2
Tables and relationserDiagram
Components and containersflowchart with subgraph (C4 style)
Type familiesclassDiagram

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 end as a node id (it closes a subgraph); use done or finish.
  • In erDiagram, attribute types are single words (numeric, not numeric(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);
  • Bearer headers 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​

  1. Pick the section folder and a short kebab-case file name; that becomes the URL.
  2. Add front matter with title and the next sidebar_position.
  3. Write the page from the sources, with tables and diagrams.
  4. End with ## Sources.
  5. Link it from the section overview, and from other pages only by absolute site path.
  6. Run pnpm run check:diagrams and the secrets grep above.
  7. Run pnpm build in website/ 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.json
  • website/scripts/check-diagrams.mjs
  • website/docs/intro.md, website/docs/*/_category_.json
  • CODING_STANDARDS.md section 5 (comments and documentation)