Start

Documentation & Deployment

This page explains how to build, serve, and deploy the docs site locally and to GitHub Pages.

Quick Commands

# Serve locally with live reload (opens browser)
./run_docs.sh --serve

# Build static site into ./site and open file URL
./run_docs.sh --build

# Deploy to GitHub Pages (gh-pages branch) and open Pages URL
./run_docs.sh --deploy

The script uses the repository-locked uv run mkdocs environment, matching CI and the Pages workflow.

What CI runs

.github/workflows/ci.yml and .github/workflows/deploy_docs.yml both build with uv run start-gate docs, which is mkdocs build --strict plus scripts.validate_repository (tracked JSON/YAML/TOML parsing and local Markdown link resolution). Run that same arm locally before landing documentation changes; see Gate entry point.

Prerequisites

GitHub Pages

Deploy from Branch

Deploy with Actions (already configured)

The repository ships .github/workflows/deploy_docs.yml, which builds the site with mkdocs build --strict and deploys it to GitHub Pages via upload-pages-artifact + deploy-pages on every push to main (and on manual workflow_dispatch). No extra workflow file is needed; the local ./run_docs.sh --deploy remains useful for previewing or ad-hoc deploys from a developer machine.

Reference: GitHub Docs — Publishing with a custom GitHub Actions workflow.

Troubleshooting

Common errors