Writing documentation
How these pages are built, how to add one, the markdown subset available, and the standing rule that a change to the system carries its documentation update with it.
The standing rule
An update to the system gets a corresponding documentation update when one applies.
If a change alters behavior an operator relies on (a command, a flag, a default, a failure mode, a governance rule), the same change updates the page that describes it. Documentation that lags the system is worse than absent documentation, because it is confidently wrong.
How a page works
Each page is one markdown file in site/src/content/docs/. The filename is the URL slug: capability-packs.md is served at /docs/capability-packs.
There is no registry to update. src/lib/docs.ts globs the directory at build time, and scripts/routes.mjs reads the same directory, so a new file automatically appears in the sidebar, the search index, sitemap.xml, and the prerender pass. A hand-maintained list is exactly what would leave a new page unindexed.
Front matter
Every file starts with a fenced block. All fields except keywords are required, and the build fails loudly if one is missing or if category is not a known section.
---
title: Capability packs
summary: One sentence that shows on the index card and as the page's meta description.
category: The organization
order: 2
keywords: capability pack, tool slot, knowledge-only
---| Field | Meaning |
|---|---|
title | Page heading, sidebar label, and document title |
summary | Index card text, the intro line, and the SEO description |
category | One of: Start here, Using Orgabot, The organization, Reference |
order | Position within the category |
keywords | Comma-separated search boosts for words that may not appear in the body |
The markdown subset
Rendering is a small in-repo parser, not a markdown library, and it produces React elements rather than an HTML string, so no page can inject markup and the site's strict script-src 'self' policy needs no exception.
Supported: ##, ### and #### headings; paragraphs; bullet and numbered lists; fenced code blocks; > callouts; pipe tables; standalone images; --- dividers; and, inline, bold with double asterisks, italic with single asterisks, code in single backticks, and links in the ordinary [text](target) form.
Anything outside that subset renders as literal text. Two conventions matter:
- `##` headings become the page's "On this page" list and its deep-link anchors, so write them as things a reader would search for.
- Internal links use the site path (
/docs/invariants), which keeps navigation client-side. External links open in a new tab automatically.
Screenshots
Put images in site/public/docs/ and reference them by absolute path:
The alt text doubles as the caption and as search text, so describe what the reader should notice in the image, not just what the image is of. Prefer WebP.
Checks that run
npm test in site/ covers the documentation as content, not just as code:
- every markdown file parses and carries valid front matter;
- slugs are unique and categories are known;
- every internal
/docs/...link resolves to a page that exists; - every referenced image exists in
public/; - every doc route appears in the shared
ROUTESlist, so the sitemap and prerender never drift; - the markdown parser and the search ranking have their own unit tests.
Run the site locally with npm run dev (port 3001) and read the page you wrote before shipping it.