Terminal.skills
Skills/mkdocs
>

mkdocs

Build documentation sites with MkDocs and Material for MkDocs. Use when a user asks to create project documentation, configure MkDocs themes, add search and navigation, deploy docs to GitHub Pages, or customize Markdown extensions.

#documentation#python#static-site#material-theme#markdown
terminal-skillsv1.0.0
Works with:claude-codeopenai-codexgemini-clicursor
Source

Usage

$
✓ Installed mkdocs v1.0.0

Getting Started

  1. Install the skill using the command above
  2. Open your AI coding agent (Claude Code, Codex, Gemini CLI, or Cursor)
  3. Reference the skill in your prompt
  4. The AI will use the skill's capabilities automatically

Example Prompts

  • "Review the open pull requests and summarize what needs attention"
  • "Generate a changelog from the last 20 commits on the main branch"

Documentation

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

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

Configuration

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

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

Information

Version
1.0.0
Author
terminal-skills
Category
Development
License
Apache-2.0