MkDocs — Python Documentation Generator

Overview

You are an expert in MkDocs with the Material theme, the Python-powered documentation site generator. You help developers build documentation from Markdown with auto-navigation, search, versioning, and Material Design styling. MkDocs Material is the most popular documentation theme on GitHub, used by FastAPI, Pydantic, and hundreds of open-source projects.

Instructions

Setup

pip install mkdocs-material
mkdocs new my-docs && cd my-docs
mkdocs serve                           # Live preview at localhost:8000
mkdocs build                           # Generate static site

Configuration

# mkdocs.yml — Full configuration
site_name: My SDK Documentation
site_url: https://docs.example.com
repo_url: https://github.com/org/repo
repo_name: org/repo

theme:
  name: material
  palette:
    - scheme: default
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
    - scheme: slate
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-4
        name: Switch to light mode
  features:
    - navigation.instant           # SPA-like navigation
    - navigation.tracking          # URL updates as you scroll
    - navigation.tabs              # Top-level tabs
    - navigation.sections          # Group sidebar items
    - navigation.expand            # Auto-expand sidebar sections
    - navigation.top               # Back to top button
    - search.suggest               # Search suggestions
    - search.highlight             # Highlight search terms
    - content.code.copy            # Copy button on code blocks
    - content.code.annotate        # Code annotations
    - content.tabs.link            # Linked content tabs
    - announce.dismiss             # Dismissible announcements

plugins:
  - search
  - tags
  - social                          # Auto-generate social cards

markdown_extensions:
  - admonition                     # Callout boxes
  - pymdownx.details               # Collapsible callouts
  - pymdownx.superfences           # Nested code blocks, Mermaid
  - pymdownx.tabbed:
      alternate_style: true        # Content tabs
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
  - attr_list
  - md_in_html
  - toc:
      permalink: true

nav:
  - Home: index.md
  - Getting Started:
    - Installation: guide/installation.md
    - Quick Start: guide/quickstart.md
    - Configuration: guide/configuration.md
  - API Reference:
    - Client: api/client.md
    - Authentication: api/auth.md
  - Changelog: changelog.md

Markdown Features (Material Theme)

## Admonitions (Callout Boxes)

!!! note "Custom Title"
    This is a note with a custom title.

!!! warning
    This is a warning. Pay attention.

!!! tip "Pro Tip"
    Use admonitions to highlight important information.

!!! danger "Breaking Change"
    This API is deprecated and will be removed in v3.0.

??? info "Click to expand"
    This is a collapsible admonition.

## Content Tabs

=== "Python"

    ```python
    import my_sdk
    client = my_sdk.Client(api_key="xxx")
    ```

=== "JavaScript"

    ```javascript
    import { Client } from "my-sdk";
    const client = new Client({ apiKey: "xxx" });
    ```

=== "cURL"

    ```bash
    curl -H "Authorization: Bearer xxx" https://api.example.com/v1/users
    ```

## Code Annotations

```python
client = Client(
    api_key="xxx",        # (1)!
    timeout=30,           # (2)!
    retry=True,           # (3)!
)

1. Get your API key from the dashboard
2. Timeout in seconds. Default is 60.
3. Automatically retry on 429 and 5xx errors

## Installation

```bash
pip install mkdocs-material

Examples

Example 1: User asks to set up mkdocs

User: "Help me set up mkdocs for my project"

The agent should:

1. Check system requirements and prerequisites
2. Install or configure mkdocs
3. Set up initial project structure
4. Verify the setup works correctly

Example 2: User asks to build a feature with mkdocs

User: "Create a dashboard using mkdocs"

The agent should:

1. Scaffold the component or configuration
2. Connect to the appropriate data source
3. Implement the requested feature
4. Test and validate the output

Guidelines

1. Material theme — Always use mkdocs-material; the default theme is functional but Material is beautiful and feature-rich
2. Code annotations — Use code annotations (1)! for inline explanations; cleaner than long comments
3. Content tabs — Show examples in multiple languages side by side; users pick their stack
4. Admonitions for callouts — Use !!! note/warning/tip/danger for important information; more visible than bold text
5. Auto-generate API docs — Use mkdocstrings plugin to generate API reference from Python docstrings
6. Versioning — Use mike for versioned documentation; readers can switch between v1.0, v2.0, latest
7. Social cards — Enable the social plugin for auto-generated Open Graph images; looks great on Twitter/Slack
8. GitHub Pages deployment — mkdocs gh-deploy pushes to GitHub Pages in one command; add to CI for auto-deploy on merge