Skip to content

Docs Site

This repo publishes its developer documentation through MkDocs and GitHub Pages.

The exact production URL is owned by the repository's GitHub Pages settings. Do not hardcode temporary Pages hostnames into source docs.

Local Preview

Install the docs dependencies:

python3 -m pip install -r requirements-docs.txt

Start the local preview server:

mkdocs serve

Open http://127.0.0.1:8000.

Static Build

mkdocs build --strict

The generated site is written to site/.

GitHub Actions Behavior

.github/workflows/docs.yml does two things:

  • on pull requests: build the docs to catch broken links or config errors
  • on main: build and deploy to GitHub Pages

workflow_dispatch is enabled for manual runs, but only the main ref is allowed to publish the live site.

The workflow asks actions/configure-pages to enable Pages with GitHub Actions as the build and deployment source. If repository or organization settings prevent workflow-based enablement, actions/configure-pages or actions/deploy-pages fails with a 404 Not Found response until a repository administrator enables Pages in the repository settings.

Authoring Guidelines

  • keep the root README.md short and route deep detail into docs/
  • put long-lived architecture and reference material under docs/
  • keep operational gotchas in docs/runbooks/
  • add or update nav entries in mkdocs.yml when you add a new page

If a product or deploy change adds a new public endpoint, auth contract, or environment variable, update the matching docs page in the same change. For this repo that usually means one of: