MkDocs: генератор документации из Markdown

Документация в репозитории устаревает быстрее, чем её читают: ссылки в README ведут в никуда, разделы разбросаны по docs/, wiki/ и confluence, а поиск по сайту не работает. MkDocs решает это предсказуемо — берёт папку с .md файлами и собирает статический сайт. Один конфиг, одна команда для прода, привычный Markdown.

Что такое MkDocs

MkDocs — статический генератор сайта документации на Python. На входе: каталог с Markdown-файлами и YAML-конфиг. На выходе: готовый site/ с HTML, который отдаётся любым веб-сервером или хостится на GitHub Pages, GitLab Pages, S3. Сам MkDocs ядро рендеринга, а внешний вид и фичи задаёт тема. Стандарт де-факто — Material for MkDocs.

Установка

Минимальные требования — Python 3.8+. Ставить лучше в виртуальное окружение, чтобы не засорять системный pip.

python3 -m venv .venv
source .venv/bin/activate
pip install mkdocs

Проверка:

mkdocs --version

Типичный вывод — mkdocs, version 1.6.x. Версия важна, потому что темы и плагины часто требуют конкретный диапазон.

Полезные пакеты, которые ставятся вместе с базой или отдельно:

pip install mkdocs-material mkdocstrings[pymdownx]

Создание проекта

Команда mkdocs new создаёт скелет:

mkdocs new my-docs
cd my-docs

Появится каталог docs/ с index.md и пустой mkdocs.yml. Это и есть рабочий минимум — больше ничего обязательного нет.

tree my-docs

my-docs
├── docs
│   └── index.md
└── mkdocs.yml

Структура каталогов

docs/ — единственный источник Markdown. Иерархия каталогов напрямую превращается в URL. Файл docs/guide/install.md становится /guide/install/. Файл index.md в корне docs/ — главная страница.

docs/
├── index.md
├── guide/
│   ├── install.md
│   └── config.md
├── reference/
│   └── cli.md
└── about.md

Сайт собирается в каталог site/ рядом с mkdocs.yml. Этот каталог — артефакт сборки, его коммитят только при ручном деплое, обычно его собирает CI.

Конфигурация mkdocs.yml

Минимальный рабочий конфиг:

site_name: My Project Docs
site_url: https://example.com/docs/
docs_dir: docs
site_dir: site

theme:
  name: material

Полный набор ключей, которые реально используются в продакшене:

Пример с навигацией, расширениями и плагинами:

site_name: Service Docs
site_url: https://docs.example.com/
repo_url: https://github.com/example/service

theme:
  name: material
  features:
    - navigation.tabs
    - navigation.sections
    - search.highlight
    - content.code.copy
  palette:
    - scheme: default
      toggle:
        icon: material/brightness-7
        name: Тёмная тема
    - scheme: slate
      toggle:
        icon: material/brightness-4
        name: Светлая тема

nav:
  - Главная: index.md
  - Руководство:
      - Установка: guide/install.md
      - Настройка: guide/config.md
  - Справка:
      - CLI: reference/cli.md

markdown_extensions:
  - admonition
  - tables
  - toc:
      permalink: true
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.superfences
  - pymdownx.tabbed:
      alternate_style: true

plugins:
  - search

Наполнение контентом

Markdown-файлы — обычный CommonMark с расширениями. Полезные конструкции, которые работают «из коробки» при включённых расширениях из примера выше.

Admonitions:

> [!NOTE]
> Краткое пояснение для читателя.

> [!WARNING]
> Действие может привести к потере данных.

Табы с pymdownx.tabbed:

=== "Linux"

    ```bash
    sudo apt install foo
    ```

=== "macOS"

    ```bash
    brew install foo
    ```

Подсветка кода с указанием языка:

```python
from mkdocs import config
print(config.DEFAULT_SCHEMA.keys())
```

Внутренние ссылки — относительные пути от текущего файла:

Подробнее в [разделе про настройку](config.md).

Внешние ссылки по умолчанию открываются в той же вкладке. Чтобы открывать в новой:

[Material for MkDocs](https://squidfunk.github.io/mkdocs-material/){target=_blank}

Сборка и локальный сервер

Локальная разработка — запуск live-сервера:

mkdocs serve

По умолчанию слушает http://127.0.0.1:8000. Полезные флаги:

Сборка артефакта для деплоя:

mkdocs build --clean --strict

--strict — обязателен в CI, иначе опечатки в ссылках и отсутствующие файлы в nav будут молча собираться. Код возврата при warning — ноль, поэтому без --strict пайплайн пройдёт зелёным с битой документацией.

Типовые ошибки при первом запуске:

• WARNING - A relative path to '...' is included in the 'nav' config. Файл указан в nav, но отсутствует в docs/. Проверьте регистр и путь.
• WARNING - Documentation file 'x.md' is not included in the 'nav' configuration. Файл есть, но в навигацию не добавлен. Либо добавьте в nav, либо положитесь на авто-навигацию, убрав секцию nav целиком.
• ERROR - Config value 'theme': The theme 'mkdocs' is not installed. Не установлен пакет темы, либо опечатка в имени.

Material for MkDocs: навигация, поиск, tabs

Material расширяет базовый MkDocs тремя вещами, которые нужны почти всегда.

Навигация. Включается через features в секции theme:

theme:
  name: material
  features:
    - navigation.tabs          # верхние табы первого уровня
    - navigation.sections      # табы приклеиваются при скролле
    - navigation.top           # кнопка «наверх»
    - navigation.indexes       # index.md превращается в секцию
    - navigation.tracking      # якорь в URL при переходе
    - toc.follow               # правое оглавление скроллится за текстом

Поиск. Плагин search идёт в составе Material, но регистрируется отдельно:

plugins:
  - search:
      separator: '[\s\-\.\_]+'

Для русской документации важно включить стемминг — search.lang: ru в конфиге theme. Список поддерживаемых языков Material публикует в документации, новые добавляются регулярно.

Tabs внутри страницы. Делаются расширением pymdownx.tabbed, которое уже подключено выше. Альтернативный синтаксис через !!! example блоки в некоторых темах не работает — это частая причина «почему табы не отрисовываются».

Подсветка кода и копирование. Кнопка «скопировать» включается фичей content.code.copy. Номера строк — расширением pymdownx.highlight с linenums: true либо глобально через markdown_extensions:

markdown_extensions:
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.superfences

Тёмная тема — обязательная опция для документации, которую читают ночью по алертам. В примере конфига выше переключатель настроен через palette с двумя схемами: default и slate. Чтобы Material отдавал правильную схему при первом заходе, добавьте в <head> пользовательский скрипт или используйте theme.palette.toggle с media — это работает без JS и учитывает системные настройки пользователя.