Skill: Build and Test Documentation

Build, test, and serve the documentation site using Zensical (recommended) or MkDocs.

When to Use

bash

# Build and serve with Zensical (primary, 20x faster)
make serve

# Or using doc-cli
./doc-cli.sh serve

# Build only (no serve)
make build

bash

# Serve with MkDocs (legacy, slower)
make mkdocs-serve

# Build with MkDocs
make mkdocs-build

System	Build Time	Use Case
Zensical	~0.4s	Primary development, production
MkDocs	~8s	Legacy support, versioning with mike

bash

make setup

This installs:

bash

# Zensical (primary)
make build

# MkDocs (legacy)
make mkdocs-build

Output goes to site/ directory. Build will:

bash

# Zensical on port 8001 (primary)
make serve

# MkDocs on port 8000 (legacy)
make mkdocs-serve

Zensical features:

If MkDocs hot reload stops working, use make serve-clean or see Hot Reload Troubleshooting.

The doc-cli provides an interactive menu:

bash

./doc-cli.sh

Available commands:

bash

# Custom Zensical server address
DEV_ADDR=0.0.0.0:8080 make serve

Expected for problem sub-pages. These are linked from parent pages, not nav.

bash

# Kill existing server
pkill -f zensical
pkill -f mkdocs

# Then restart
make serve

bash

# Ensure PYTHONPATH is set
export PYTHONPATH=$PYTHONPATH:$(pwd)
make build