Docs & Tooling

This site is built with MkDocs + Material. Everything lives under docs/.

Running the Docs Locally

cd docs
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cd ..
npx nx serve docs

Open http://127.0.0.1:8000/ to preview changes with live reload.

Faster installs

If you already have MkDocs + Material globally, you can skip the virtualenv and just pip install mkdocs-material pymdown-extensions.

Structure

• docs/pages – Markdown sources.
• docs/mkdocs.yml – site metadata + navigation.
• docs/site – build output (ignored by git; generated via mkdocs build).

Writing Guidelines

• Use Markdown features already enabled: admonition, pymdownx.details, pymdownx.highlight, superfences, inlinehilite, footnotes, and attr_list.
• Prefer short sections with clear headings (##). Material automatically builds the table of contents.
• Use !!! note|tip|warning for callouts.

Building / Publishing

cd docs
mkdocs build

Outputs static assets to docs/site. Our deployment pipeline uploads those files to the hosting bucket when we cut a release.

Updating Navigation

1. Edit docs/mkdocs.yml.
2. Run npx nx serve docs to confirm the new nav renders correctly.
3. Keep the nav order aligned with the documentation plan (Overview → User Guide → Developer Guide → Reference).

Linting Markdown

Run npx remark docs/pages --quiet if you have remark configured locally. Otherwise rely on MkDocs build warnings for now.