MkDocs

Material for MkDocs is the static-site generator and theme used by this repository. The site source lives in docs/, and mkdocs.yml controls the theme and navigation.

Local setup

Create and activate a virtual environment from the repository root:

python3 -m venv .venv
source .venv/bin/activate

Install the build dependencies:

python -m pip install --upgrade pip mkdocs-material pillow cairosvg

Write and preview

Add or update Markdown files under docs/. When adding a new page, add it to the appropriate section of nav in mkdocs.yml; pages not listed there will not appear in the site navigation.

Start the local development server:

mkdocs serve

MkDocs prints the local URL, normally http://127.0.0.1:8000, and rebuilds the site when files change.

Validate

Build the static site before committing. This checks the configuration and renders every page into the ignored site/ directory.

mkdocs build

Do not run mkdocs new . in this existing repository; that command is for bootstrapping a new project and may overwrite starter files.

Deployment

The GitHub Actions workflow deploys the site with mkdocs gh-deploy --force after a push to main or master. The workflow installs the same dependencies used above, so a successful local build is a useful pre-push check.

For theme and configuration options, see the Material for MkDocs documentation.