# Mkdocs Generation

> Generate MkDocs documentation sites with Material theme, mkdocstrings for API docs, and versioning. Use when setting up or extending project documentation.

- Skill: `majiayu000/mkdocs-generation` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/mkdocs-generation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/mkdocs-generation/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/mkdocs-generation

---


# 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):

```toml
[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:
1. **Site metadata**: name, description, URLs
2. **Versioning**: mike provider for multi-version docs
3. **Theme**: Material with navigation features
4. **Plugins**: search + mkdocstrings for API docs
5. **Navigation**: Explicit nav structure

## API Reference with mkdocstrings

Create minimal markdown files that reference Python modules:

```markdown
# 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

```bash
# 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

1. **index.md**: Brief overview, key features as bullet list, installation snippet, "Where to Next" links
2. **getting-started.md**: Prerequisites, step-by-step setup, minimal working example
3. **API docs**: Let mkdocstrings generate from docstrings; add brief intro if needed
4. **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