Skip to content

Deploying these docs

The documentation site is built with MkDocs Material and auto-deploys to Cloudflare Pages on every push to main.

Cloudflare Pages setup (one time)

Create a separate Pages project from the engineer portal (the portal is portal/; docs build from the repo root).

  1. Cloudflare dashboard → Workers & Pages → Create → Pages → Connect to Git → select this repository.
  2. Build settings:
  3. Framework preset: None.
  4. Build command: pip install -r requirements.txt && mkdocs build
  5. Build output directory: site
  6. Root directory: / (repo root).
  7. Environment variables:
  8. PYTHON_VERSION = 3.12
  9. Save & Deploy. Every push to main rebuilds and publishes automatically.

These docs include internal architecture (build plan, security model). Protect the Pages hostname with Cloudflare Access using the same Entra SSO app as the backend/portal:

Zero Trust → Access → Applications → add a Self-hosted app for the docs hostname → allow your org's Entra group.

Local preview

pip install -r requirements.txt
mkdocs serve     # http://127.0.0.1:8000
mkdocs build --strict   # what CI runs; fails on broken links/nav

Adding a page

Create docs/<name>.md and add it to the nav: list in mkdocs.yml. CI runs mkdocs build --strict, so a page that isn't in the nav or has a broken link will fail the build before it ships.