home / skills / julianobarbosa / claude-code-skills / mkdocs-skill

mkdocs-skill skill

needs review

This skill helps you create, configure, and deploy Markdown-based documentation sites with MkDocs efficiently and consistently.

npx playbooks add skill julianobarbosa/claude-code-skills --skill mkdocs-skill

Review the files below or copy the command above to add this skill to your agents.

Files (9)

SKILL.md

6.4 KB

---
name: mkdocs
description: Build project documentation sites with MkDocs static site generator. USE WHEN user mentions mkdocs, documentation site, docs site, project documentation, OR wants to create, configure, build, or deploy documentation using Markdown. Covers installation, configuration, theming, plugins, and deployment.
allowed-tools:
  - Bash # Enables mkdocs commands and previews
  - Glob
  - Grep
  - LS
  - Read
---

# MkDocs Documentation Site Generator

MkDocs is a fast, simple static site generator for building project documentation from Markdown files. Configuration uses a single YAML file (`mkdocs.yml`).

## Quick Start

### Installation

```bash
# Install MkDocs
pip install mkdocs

# Verify installation
mkdocs --version
```

### Create New Project

```bash
# Create project structure
mkdocs new my-project
cd my-project

# Start development server
mkdocs serve
```

**Project Structure Created:**

```
my-project/
├── mkdocs.yml      # Configuration file
└── docs/
    └── index.md    # Homepage
```

### Minimal Configuration

```yaml
# mkdocs.yml
site_name: My Project
site_url: https://example.com/
nav:
  - Home: index.md
  - About: about.md
```

## Core Commands

| Command              | Purpose                           |
| -------------------- | --------------------------------- |
| `mkdocs new PROJECT` | Create new project                |
| `mkdocs serve`       | Start dev server (localhost:8000) |
| `mkdocs build`       | Build static site to `site/`      |
| `mkdocs gh-deploy`   | Deploy to GitHub Pages            |
| `mkdocs get-deps`    | Show required packages            |

**Common Options:**

- `-f, --config-file FILE` - Use custom config file
- `-s, --strict` - Fail on warnings
- `-d, --site-dir DIR` - Custom output directory
- `--dirty` - Only rebuild changed files
- `--clean` - Clean output before build

## Project Structure

```
project/
├── mkdocs.yml              # Configuration (required)
├── docs/
│   ├── index.md            # Homepage
│   ├── about.md            # Additional pages
│   ├── user-guide/
│   │   ├── index.md        # Section homepage
│   │   ├── getting-started.md
│   │   └── configuration.md
│   ├── img/                # Images
│   │   └── logo.png
│   └── css/                # Custom CSS
│       └── extra.css
└── custom_theme/           # Theme customizations (optional)
    └── main.html
```

## Navigation Configuration

```yaml
# Automatic navigation (alphabetically sorted)
# Omit nav key to auto-generate

# Explicit navigation with sections
nav:
  - Home: index.md
  - User Guide:
      - Getting Started: user-guide/getting-started.md
      - Configuration: user-guide/configuration.md
  - API Reference: api/
  - External Link: https://example.com/
```

## Writing Documentation

### Internal Links

```markdown
# Link to another page

[See Configuration](configuration.md)

# Link to page in another directory

[Installation](../getting-started/installation.md)

# Link to section anchor

[See Options](configuration.md#options)
```

### Page Metadata

```yaml
---
title: Custom Page Title
description: Page description for SEO
authors:
  - John Doe
date: 2024-01-01
---
# Page Content Here
```

### Code Blocks

````markdown
```python
def hello():
    print("Hello, World!")
```
````

### Tables

```markdown
| Header 1 | Header 2 |
| -------- | -------- |
| Cell 1   | Cell 2   |
```

## Theme Configuration

### Built-in Themes

```yaml
# Default MkDocs theme
theme:
  name: mkdocs
  color_mode: auto           # light, dark, auto
  user_color_mode_toggle: true
  nav_style: primary         # primary, dark, light
  highlightjs: true
  navigation_depth: 2
  locale: en

# ReadTheDocs theme
theme:
  name: readthedocs
  prev_next_buttons_location: bottom
  navigation_depth: 4
  collapse_navigation: true
```

### Material for MkDocs (Popular Third-Party)

```bash
pip install mkdocs-material
```

```yaml
theme:
  name: material
  palette:
    primary: indigo
    accent: indigo
  features:
    - navigation.tabs
    - navigation.sections
    - search.suggest
```

### Custom CSS/JavaScript

```yaml
extra_css:
  - css/extra.css

extra_javascript:
  - js/extra.js
  - path: js/analytics.mjs
    type: module
```

## Plugins

```yaml
plugins:
  - search:
      lang: en
      min_search_length: 3
  - tags
  - blog
```

**Popular Plugins:**

- `search` - Full-text search (built-in, enabled by default)
- `blog` - Blog functionality (Material theme)
- `tags` - Content categorization
- `social` - Social media cards

> **Note:** Defining `plugins` disables defaults. Add `- search` explicitly.

## Markdown Extensions

```yaml
markdown_extensions:
  - toc:
      permalink: true
      separator: "-"
  - tables
  - fenced_code
  - admonition
  - pymdownx.highlight
  - pymdownx.superfences
```

## Deployment

### GitHub Pages

```bash
# Deploy to gh-pages branch
mkdocs gh-deploy

# With options
mkdocs gh-deploy --force --message "Deploy docs"
```

### Build for Any Host

```bash
# Build static files
mkdocs build

# Files output to site/ directory
# Upload to any static host
```

### Custom Domain

Create `docs/CNAME` file:

```
docs.example.com
```

## Common Workflows

### New Documentation Project

1. Create project: `mkdocs new my-docs`
2. Edit `mkdocs.yml` with site_name and nav
3. Add Markdown files to `docs/`
4. Preview: `mkdocs serve`
5. Build: `mkdocs build`
6. Deploy: `mkdocs gh-deploy`

### Quick Build Preview

`Bash(mkdocs build --dry-run)`

If clean: `Bash(mkdocs serve -v)` (dev preview).

### Add New Section

1. Create directory: `docs/new-section/`
2. Add `index.md` and content files
3. Update `nav` in `mkdocs.yml`
4. Preview and verify links

### Customize Theme

1. Set `theme.custom_dir: custom_theme/`
2. Create override files matching theme structure
3. Use template blocks to extend base templates

### Safe Preview Workflow

1. Check MkDocs: `Bash(which mkdocs || echo "Install: pip install mkdocs")`
2. Dry-run build: `Bash(mkdocs build --dry-run)`
3. List issues: `Grep -r "ERROR" site/`

## Detailed References

- **Configuration options:** See [references/configuration.md](references/configuration.md)
- **Theme customization:** See [references/themes.md](references/themes.md)
- **Plugin development:** See [references/plugins.md](references/plugins.md)
- **Deployment strategies:** See [references/deployment.md](references/deployment.md)
- **Best practices:** See [references/best-practices.md](references/best-practices.md)

Overview

This skill helps you create, configure, build, and deploy documentation sites using MkDocs, a static site generator that converts Markdown into a polished documentation website. It covers installation, project structure, navigation, theming, plugins, markdown extensions, and common deployment workflows. Use it to get a docs site up quickly or to customize an existing documentation pipeline.

How this skill works

The skill inspects user intent for tasks like installation, creating a new project, configuring mkdocs.yml, theming, adding plugins, and deploying the built site. It provides concrete commands (pip install, mkdocs new/serve/build/gh-deploy), configuration snippets for navigation, theme and plugin setups, and guidance for linking, page metadata, and assets. It also recommends safe preview and build workflows and common options to customize builds.

When to use it

You want to start a new docs site from Markdown with minimal setup.
You need examples for mkdocs.yml navigation, themes, or markdown extensions.
You want to apply a third-party theme such as Material for MkDocs.
You need to add search, blog, tags, or other plugins and understand plugin defaults.
You plan to build and deploy docs to GitHub Pages or any static host.

Best practices

Keep a single mkdocs.yml at the project root and organize pages under docs/ with index.md for each section.
Explicitly define nav in mkdocs.yml for predictable ordering; omit nav only for small auto-generated sites.
Enable a dry-run build and local serve for previews (mkdocs build --dry-run, mkdocs serve) before deployment.
When adding plugins, include built-in search explicitly if you define a plugins list.
Use page metadata (YAML front matter) for SEO and author/date information and consistent titles.

Example use cases

Create a new docs site: pip install mkdocs; mkdocs new my-project; mkdocs serve to preview locally.
Configure navigation and sections with a structured nav key to reflect your product docs hierarchy.
Apply Material theme: pip install mkdocs-material and set theme.name: material with palette and features.
Add plugins and markdown extensions for search, tags, and enhanced code rendering (pymdownx.superfences).
Deploy documentation to GitHub Pages with mkdocs gh-deploy or build to site/ and upload to any static host.

FAQ

How do I deploy to a custom domain?

Create a CNAME file under docs/ containing your domain and deploy normally; configure DNS to point to the host.

What happens when I define plugins in mkdocs.yml?

Defining plugins disables MkDocs defaults, so add built-in search explicitly if you still want it enabled.