К основному содержанию
скилл CX Codex

mkdocs — скилл для Claude Code: документация и установка

Скилл для Claude Code помогает создать и настроить сайт документации на MkDocs из Markdown-файлов. Помогает собрать, локально просматривать и публиковать сайт.

MIT 157 установок ★ 17 обновлён 2026-10-14

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add julianobarbosa/claude-code-skills --skill mkdocs -a claude-code
Открыть на GitHub

Что делает mkdocs

Скилл проводит через создание проекта командой mkdocs new, настройку mkdocs.yml и подготовку страниц в docs/. Он помогает задать навигацию, выбрать тему, настроить плагины и расширения Markdown, а затем собрать сайт или опубликовать его в GitHub Pages.

Для работы MkDocs устанавливают через pip install mkdocs. Локальный просмотр запускается командой mkdocs serve, сборка — mkdocs build; статические файлы попадают в site/. Если в mkdocs.yml перечислить плагины, стандартный поиск отключится, поэтому добавьте - search явно. Это важно: иначе поиск по страницам перестанет работать.

Какие задачи решает

  • создать каркас сайта документации
  • настроить навигацию по Markdown-страницам
  • выбрать тему и подключить плагины
  • проверить сайт локально перед публикацией
  • опубликовать документацию в GitHub Pages

Примеры запросов агенту

  • Создай сайт документации на MkDocs в новом проекте и настрой навигацию.
  • Проверь mkdocs.yml: добавь плагин тегов и сохрани поиск по страницам.
  • Собери документацию и подготовь её к публикации в GitHub Pages.

Как установить mkdocs

1Через Skills CLI (Vercel)

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

2Вручную: положить файлы

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

Папка скилла целиком; для одного проекта — .claude/skills/mkdocs/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о mkdocs

Как установить mkdocs в Claude Code?

Выполните npx skills add julianobarbosa/claude-code-skills --skill mkdocs -a claude-code. Файл скилла находится по пути ~/.claude/skills/mkdocs/SKILL.md.

Что делает скилл mkdocs?

Он помогает создавать сайты документации из Markdown: настраивать mkdocs.yml, навигацию, темы и плагины, собирать сайт и публиковать его в GitHub Pages.

Почему поиск MkDocs перестаёт работать после настройки плагинов?

Когда в mkdocs.yml задан список plugins, стандартный поисковый плагин отключается. Добавьте - search в этот список явно.

Исходный текст

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

Похожие скиллы

Все скиллы по теме «Тексты и документация» →
kubernetes-mkdocs-documentation-cursorrules-prompt PatrickJS Правило kubernetes-mkdocs-documentation-cursorrules-prompt задаёт Cursor роль технического писателя: агент пишет документацию по Kubernetes и cloud native в Markdown и MkDocs. CX Codex +1 ★ 41 178звёзд репо mkdocs-mcp ubaumann Открывает статьи и структуру MkDocs как ресурсы MCP, давая агенту прямой доступ к локальной документации. CX Codex +1 ★ 9звёзд репо mkdocs-translations официальный github Скилл mkdocs-translations для GitHub Copilot переводит документацию MkDocs на заданный язык, сохраняя структуру папок и Markdown и обновляя конфиг i18n. Автоматизирует локализацию документации с английского на другие языки. CX Codex +1 8 800установок developer-docs-structure-audit Samuel Berthe Скилл developer-docs-structure-audit для Claude Code, Codex, Cursor и других сред проводит аудит информационной архитектуры документации. Находит страницы не на своём месте и пробелы в структуре по методологии Diátaxis. CX Codex +1 13 700установок agent-technical-writer Tony363 Скилл agent-technical-writer для Claude Code пишет API-документацию, гайды и технические материалы. Подключается к задачам технического писателя и подготовке технических рекомендаций. CX Codex +1 108установок project-wiki robertguss Скилл project-wiki организует внутри репозитория вики по методике Карпатого: агент сам создаёт страницы, ведёт перекрёстные ссылки и проверяет целостность. CX Codex +1 ★ 139звёзд репо

Из того же набора37

Весь набор →
obsidian Учит агента работать с вольтом Obsidian: структура .obsidian/, плагины на TypeScript, ссылки obsidian:// и Local REST API для запросов к заметкам. CX Codex +1 244установок argocd-advanced Скилл argocd-advanced для Claude Code разбирает продвинутые операции ArgoCD: ApplicationSet, автообновление образов и ввод кластера в GitOps-контур. CX Codex +1 231установок researching-web Скилл researching-web отправляет вопрос в Perplexity через MCP и возвращает разбор по теме: свежие релизы, сравнения технологий, принятые практики. CX Codex +1 200установок 1password Учит агента работать с 1Password: доставать секреты через op, подставлять их в окружение и отдавать в Kubernetes. CX Codex +1 172установок loki Скилл помогает настраивать Grafana Loki: выбирать режим развёртывания и хранилище, задавать параметры и писать запросы LogQL. Пригодится при внедрении Loki и разборе проблем. CX Codex +1 148установок consulting-design Скилл consulting-design подключает Gemini к обсуждению архитектуры, поиску компромиссов и генерации проектных альтернатив через MCP-инструменты. CX Codex +1 140установок opentelemetry Скилл по OpenTelemetry: помогает агенту настроить коллектор, развернуть его в Kubernetes и связать приёмники, процессоры и экспортёры в рабочие пайплайны. CX Codex +1 135установок writing-python Скилл writing-python держит агента в правилах Python 3.14+: сначала стандартная библиотека, аннотации типов у всех функций, uv и ruff вместо pip и black. CX Codex +1 134установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой