What is mkdocs-generation?

This Claude skill automates the generation of professional-grade documentation sites using MkDocs and the Material theme. It streamlines the technical writing process by integrating mkdocstrings for automatic API documentation from Python source code and mike for efficient version management, ensuring your project's documentation is always modern, searchable, and up-to-date.

When should I use mkdocs-generation?

mkdocs-generation is useful in the following scenarios: • Bootstrap a new project documentation site with a responsive Material Design theme and optimized navigation structure. • Automate the creation of comprehensive API reference manuals by extracting docstrings directly from Python modules using mkdocstrings. • Implement documentation versioning to allow users to switch between different releases (e.g., v1.0, v2.0, latest) of a software product. • Standardize technical documentation across multiple repositories using consistent templates, directory structures, and writing guidelines.

name	mkdocs-generation
description	Generate MkDocs documentation sites with Material theme, mkdocstrings for API docs, and versioning. Use when setting up or extending project documentation.

MkDocs Documentation Generation

Generate professional documentation sites using MkDocs Material theme with automatic API reference generation.

Stack

MkDocs: Static site generator for project documentation
Material Theme: Modern, responsive theme with navigation features
mkdocstrings: Auto-generate API docs from Python docstrings
mike: Version management for documentation

Dependencies

Add to pyproject.toml (optional extras group):

[project.optional-dependencies]
docs = [
    "mkdocs>=1.5",
    "mkdocs-material>=9.4",
    "mkdocstrings[python]>=0.24",
    "mike>=2.0",
]

Or requirements.txt:

mkdocs>=1.5
mkdocs-material>=9.4
mkdocstrings[python]>=0.24
mike>=2.0

Directory Structure

Simple (flat):

docs/
├── index.md           # Home/overview
├── getting-started.md # Installation and quickstart
├── configuration.md   # Config options
└── tools.md          # Feature reference

Complex (nested):

docs/
├── index.md
├── compatibility.md
├── guide/
│   ├── getting-started.md
│   ├── cli.md
│   └── advanced.md
└── api/
    ├── panel.md       # ::: module.Class
    └── entities/
        ├── area.md
        └── zone.md

mkdocs.yml Configuration

See templates/mkdocs.yml for the full configuration template.

Key sections:

Site metadata: name, description, URLs
Versioning: mike provider for multi-version docs
Theme: Material with navigation features
Plugins: search + mkdocstrings for API docs
Navigation: Explicit nav structure

API Reference with mkdocstrings

Create minimal markdown files that reference Python modules:

# Panel API

::: mypackage.panel.Panel

::: mypackage.panel.PanelSync

mkdocstrings auto-generates documentation from docstrings. Configure in mkdocs.yml:

docstring_style: google - Use Google-style docstrings
show_source: false - Hide source code
merge_init_into_class: true - Combine __init__ with class docs
filters: ["!^_"] - Exclude private members

Commands

# Serve locally with hot-reload
mkdocs serve

# Build static site
mkdocs build

# Deploy to GitHub Pages
mkdocs gh-deploy

# Version management (mike)
mike deploy --push --update-aliases 0.1.0 latest
mike set-default --push latest

Writing Guidelines

index.md: Brief overview, key features as bullet list, installation snippet, "Where to Next" links
getting-started.md: Prerequisites, step-by-step setup, minimal working example
API docs: Let mkdocstrings generate from docstrings; add brief intro if needed
Guides: Task-oriented, include code examples, link to related API docs

Templates

templates/mkdocs.yml - Configuration file
templates/index.md - Home page
templates/getting-started.md - Quickstart guide
templates/api-reference.md - API doc page using mkdocstrings

mkdocs-generation

When & Why to Use This Skill

Use Cases