Skill: Build and Test Documentation

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

When to Use

• Before committing documentation changes
• After adding or modifying pages
• Debugging build errors
• Previewing changes locally

Quick Commands

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

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

# Build only (no serve)
make build

Legacy MkDocs Commands

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

# Build with MkDocs
make mkdocs-build

Build Systems Comparison

Build Process

1. Setup (First Time)

make setup

This installs:

• Python dependencies from requirements.txt
• Zensical and MkDocs
• Local plugins from mkdocs_plugins/ (editable install)

2. Build

# Zensical (primary)
make build

# MkDocs (legacy)
make mkdocs-build

Output goes to site/ directory. Build will:

• Compile all markdown to HTML
• Process navigation structure
• Validate internal links

3. Serve Locally

# Zensical on port 8001 (primary)
make serve

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

Zensical features:

• Blazing fast rebuilds (~0.4s)
• Hot reload on file changes
• Modern architecture

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

Using Doc-CLI

The doc-cli provides an interactive menu:

./doc-cli.sh

Available commands:

• serve - Start Zensical dev server (port 8001)
• build - Build with Zensical
• mkdocs-serve - Start MkDocs dev server (legacy)

Environment Variables

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

Troubleshooting

"Page not in nav" Warning

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

Port Already in Use

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

# Then restart
make serve

Import Errors (MkDocs only)

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

Checklist

• Run make setup if dependencies changed
• Run make build to validate
• Check for ERROR messages
• Run make serve to preview
• Verify navigation works
• Check responsive layout