This page explains how to build, serve, and deploy the docs site locally and to GitHub Pages.
# 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.
.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.
mkdocs.yml at repository rootuv with the locked development environment (uv sync --all-extras --dev)mkdocs gh-deploy --force, publishing to the gh-pages branch.gh-pages automatically when configured to “Deploy from a branch”.https://<org>.github.io/<repo>/.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.
uv sync --all-extras --dev before retrying.mkdocs.yml exists at the repo root.nav.uv, then run uv sync --all-extras --dev.gh-pages branch.mkdocs.yml nav: entries match file names.