Build and Serve the Documentation

The project documentation is a Zensical static site configured by zensical.toml.

Run all commands from the repository root.

Install dependencies

Install the development and documentation dependency groups:

uv sync --group dev --group docs

Activating .venv is optional because uv run selects the project environment.

Start the preview server

uv run --group docs zensical serve

Open http://127.0.0.1:8000. Zensical watches the documentation and Python source trees, rebuilds changed pages, and serves the updated site. Stop the server with Ctrl+C.

Use a different address when port 8000 is occupied:

uv run --group docs zensical serve \
  --dev-addr 127.0.0.1:8001

Pass --open to open the preview in the default browser automatically.

Build the static site

Build with strict validation:

uv run --group docs zensical build --strict

Strict mode fails on documentation warnings, including invalid navigation and API-reference problems. Generated files are written to site/, which is ignored by Git.

Force a clean build when checking cache-sensitive changes:

uv run --group docs zensical build --clean --strict

Documentation layout

Before committing documentation changes, run the strict build and inspect the affected pages in the preview server.