MkDocs Material Documentation

Diagram Rules

REQUIRED SUB-SKILL: Use mermaidjs-v11 for all Mermaid diagram creation.

Diagrams with more than 15 nodes or lines must be split:

1. Create a top-level overview showing high-level blocks only
2. Create per-component deep-dives with internal details
3. Store each diagram in docs/architecture/_includes/ as a separate .md file
4. Reference from pages using {% include-markdown %} directives
5. Add hide: true to _includes/.pages to exclude from navigation

See includes.md for the full pattern.

Common Patterns

Admonition with Code

!!! example "Usage"

    ```python
    from module import func
    func()
    ```

Tabbed Content

=== "pip"

    ```bash
    pip install package
    ```

=== "uv"

    ```bash
    uv add package
    ```

Workflow

1. Write content — use references for formatting syntax
2. Diagrams — invoke mermaidjs-v11 skill, split large diagrams into _includes/
3. Preview — uv run mkdocs serve for live reload
4. Validate — uv run mkdocs build --strict catches issues

Validation Commands

# Dev server with live reload
uv run mkdocs serve

# Strict build (CI validation)
uv run mkdocs build --strict

# Quick dirty reload during editing
uv run mkdocs serve --dirty

Dependencies

Managed via pyproject.toml + uv sync:

[project]
dependencies = [
    "mkdocs-material",
    "mkdocs-awesome-nav",
    "mkdocs-glightbox",
    "mkdocs-macros-plugin",
    "mkdocs-include-markdown-plugin",
]

Dockerfile uses uv from ghcr.io/astral-sh/uv:0.11.0.