Skip to content
Skills Library
Programming · Building & coding

mkdocs

/mkdocs

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.

Licence
MIT
Last repository change
14.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
9
Scripts
0
HTML comments
0
URLs in SKILL.md
2
Deprecation

No signals detected. Repository changed on 14.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

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.

Original author 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.

How it works

  1. Quick Start
  2. Core Commands
  3. Project Structure
  4. Navigation Configuration
  5. Writing Documentation
  6. Theme Configuration
  7. Plugins
  8. Markdown Extensions
  9. Deployment
  10. Common Workflows
Original SKILL.md headings · 323 lines, 984 words
SKILL.md preview
---
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.
Files in this package (9)
  • SKILL.md 8 KB
  • references/api-docs.md 12 KB
  • references/best-practices.md 8 KB
  • references/configuration.md 7 KB
  • references/deployment.md 8 KB
  • references/diagrams.md 9 KB
  • references/plugins.md 10 KB
  • references/themes.md 9 KB
  • references/versioning.md 9 KB

Versions

RepositoryScoreLicence
This page · julianobarbosa/claude-code-skills100MIT
TerminalSkills/skills100Apache-2.0

Database snapshot: 13.11.2026 · package version c88ebfcc3f62 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100mkdocs-config-generator
    Generate mkdocs config generator operations. Auto-activating skill for Technical Documentation. Triggers on: mkdocs config generator, mkdocs config generator Part of the Technical Documentation skill category. Use when configuring systems or services. Trigger with phrases like…
  • 100mkdocs-shadcn
    mkdocs-shadcn 主题 Markdown 排版与项目编排。当用户需要编写或修改 mkdocs-shadcn 主题的文档、配置 mkdocs.yml、或询问排版语法时,使用此技能。触发词:mkdocs、shadcn、排版、配置、Markdown、文档、admonition、details、tab、提示框、折叠、标签页、格式化、模板。
  • 95docs-manager
    Documentation management workflow for MkDocs sites and standalone markdown files -- initialize, generate, update docs, and create change summaries. Use when asked to "create docs", "write README", "update documentation", "generate docs site", "write CONTRIBUTING", "manage…
  • 95docs-manager
    Documentation management workflow for MkDocs sites and standalone markdown files -- initialize, generate, update docs, and create change summaries. Use when asked to "create docs", "write README", "update documentation", "generate docs site", "write CONTRIBUTING", "manage…
  • 100sourcey
    Build, migrate and review documentation sites with Sourcey, the open-source static docs generator for Markdown guides, OpenAPI and MCP references, Doxygen, Go and Rust. Use when creating a docs site, moving one from Docusaurus, MkDocs, Mintlify or Astro (Starlight), adding an…
  • 90doc-writer-doc-site
    Authors documentation-site pages and designs information architecture — navigation, sidebar taxonomy, page hierarchy, cross-linking strategy, doc-site generator conventions (Docusaurus, MkDocs, Nextra, VitePress, etc.). Pulled by the `doc-writer` specialist. TRIGGER: \"build out…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.