Contributing to the docs
- The portal is MkDocs Material (pinned 9.8.x; Material declares end of life on 2027-05-05 and
recommends Zensical, which reads
mkdocs.yml: see the ADR amendment in ADR-011).make docsrunsmkdocs build --strict. - Licenses: the text of the docs is CC BY 4.0; the code examples (
docs/examples/) are Apache-2.0 (see License). - No CDN: no external fonts, scripts or images (air-gapped installs); a test scans the HTML.
- Code shown in a page is included from
docs/examples/with--8<--and every example declares# expect: <substring>;python docs/gen/run_examples.pyruns them against a server. - Generated pages: node guides (
python docs/gen/node_pages.py), API reference (python docs/gen/api_page.py), Python SDK API (python docs/gen/sdk_page.py),llms.txtandllms-full.txt(python docs/gen/llms.py). Each has--check, run in CI.
Convention (T47): a ticket that adds endpoints tags them mcp when an agent should use them
(see MCP), adds or updates their documentation page and adds a runnable example in
docs/examples/. A new node type needs its page in docs/nodes/types/ (CI fails without it).
Examples gallery (T58): docs/examples/*.md are generated pages: each case lives in
scripts/docs_gallery/cases.py (invented documents, the workflow graph and what the scripted fake
model answers). python scripts/docs_examples.py --write regenerates the PDFs, workflow.json, the
Python / TypeScript / curl programs and the pages, runs the three programs against an in-process
server (real API, interpreter and Postgres; fake parse engine and fake model) and stores the answer
as response.json. make docs runs --check: every program must run and print what is stored.
It needs Postgres (Docker or DX_TEST_DATABASE_URL), node 22+, curl and jq. The monthly pages of
docs/changelog/ come from CHANGELOG.md with python scripts/docs_changelog.py (--check in
make docs; api.md is written by hand).