Skip to main content
skill CX Codex

mkdocs — Claude Code skill for docs sites and setup

This skill guides an agent through building a MkDocs documentation site from Markdown. Use it to configure pages, preview a site, or prepare a deployment.

MIT 157 installs ★ 17 updated 2026-10-14

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add julianobarbosa/claude-code-skills --skill mkdocs -a claude-code
Open on GitHub

What mkdocs does

The skill covers starting a project with mkdocs new, editing mkdocs.yml, and adding pages under docs/. It can guide navigation setup, theme selection, Markdown extensions, and plugins, then help build the static site or publish it to GitHub Pages.

Install MkDocs with pip install mkdocs. Run mkdocs serve to preview locally and mkdocs build to write the output to site/. One configuration detail matters: adding a plugins list in mkdocs.yml turns off the default search plugin. Include - search in the list or the site search will return no results.

What it helps with

  • create a documentation site project
  • set navigation for Markdown pages
  • configure a theme and plugins
  • preview a site before publishing
  • deploy documentation to GitHub Pages

Example prompts for the agent

  • Create a MkDocs documentation site for this project and set up its navigation.
  • Update mkdocs.yml to add tag support while keeping page search enabled.
  • Build the docs site and prepare it for GitHub Pages.

How to install mkdocs

1Skills CLI (Vercel)

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

2Manually: put the files in place

~/.claude/skills/mkdocs/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/mkdocs/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about mkdocs

How do I install mkdocs in Claude Code?

Run npx skills add julianobarbosa/claude-code-skills --skill mkdocs -a claude-code. The skill file is at ~/.claude/skills/mkdocs/SKILL.md.

What does the mkdocs skill do?

It guides the creation of Markdown-based documentation sites, including configuration, navigation, themes, plugins, local builds, and GitHub Pages deployment.

Why does MkDocs search stop working after I add plugins?

Adding a plugins list to mkdocs.yml disables the default search plugin. Add - search to the list to keep site search enabled.

Source text

SKILL.md · MIT
---
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)

---

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

© julianobarbosa · MIT · julianobarbosa/claude-code-skills

Similar skills

All skills for Writing and docs →

From the same set37

The whole set →
obsidian Teaches the agent how an Obsidian vault is laid out, how to write plugins for it, and how to drive notes from outside through obsidian:// links or the Local REST API. CX Codex +1 244installs argocd-advanced argocd-advanced covers the automation side of ArgoCD: ApplicationSet generators, automatic image updates and bringing a new cluster into a GitOps setup. Reach for it when sync and diff commands are not enough. CX Codex +1 231installs researching-web researching-web — a skill that routes your question to Perplexity over MCP and brings back a written answer: current releases, technology comparisons, accepted practice. CX Codex +1 200installs 1password Gives the agent a working map of 1Password: pull a secret with op, feed it to your app, wire vaults into Kubernetes. CX Codex +1 172installs loki This skill guides Grafana Loki configuration, from deployment modes and storage backends to LogQL queries. Use it while setting up Loki or investigating its configuration. CX Codex +1 148installs consulting-design consulting-design brings Gemini into your workflow to evaluate design trade-offs, review architecture, and brainstorm alternatives via MCP tools. CX Codex +1 140installs opentelemetry Walks the agent through OpenTelemetry work: collector config, rollout to Kubernetes, pipelines for traces, metrics and logs. CX Codex +1 135installs writing-python writing-python — a skill that keeps an agent on Python 3.14 idioms: standard library first, type hints on every function, uv and ruff in place of pip and black. CX Codex +1 134installs

Project sponsors

Companies that keep this analytics open