mkdocs

What this skill does

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

---

## Gotchas

- **`mkdocs serve` watches `docs/` and `mkdocs.yml` but NOT files included via `include_dir` or theme overrides** — edits to `custom_theme/main.html` don't trigger reload. Restart the server.
- **Defining `plugins:` in mkdocs.yml disables the default search plugin** — pages stop being indexed and the search box returns nothing. Always include `- search` explicitly when listing plugins.
- **`mkdocs gh-deploy` force-pushes to `gh-pages`** — any manual edits or other branches deployed there get destroyed silently. Use `--no-history` for clean history but never edit `gh-pages` by hand.
- **`use_directory_urls: true` (default) changes link semantics:** `page.md` becomes `page/` not `page.html`. Relative links in raw Markdown that worked locally as files break on the deployed site.
- **`strict: true` fails on warnings including unrecognized config keys** — adding a Material-theme-only option to a config that uses the default theme fails the build, not just warns. Check theme compatibility before enabling strict.
- **Material theme's `navigation.instant` feature breaks third-party JS** that runs on page load — analytics, Mermaid, MathJax all need explicit `document$.subscribe()` hooks instead of `DOMContentLoaded`.
- **`mkdocs build --dirty` skips unchanged files** but doesn't detect changes to navigation or theme config — pages render with stale nav. Use `--clean` (default) or delete `site/` when in doubt.