MkDocs: документация проекта как сайт

Документация живёт дольше кода, если её легко править и удобно читать. MkDocs превращает набор Markdown-файлов в статический сайт: с навигацией, поиском, подсветкой кода и тёмной темой. На выходе получается обычный каталог HTML, который можно положить на nginx, отдать с Git-хостинга или упаковать в контейнер. В статье — установка, рабочий mkdocs.yml, сборка, публикация и проверки, которые ловят битые ссылки до того, как их увидит читатель.

Зачем документации генератор

Когда руководство лежит в репозитории рядом с кодом, оно обновляется тем же коммитом, что и функция. Это главный выигрыш подхода docs-as-code: изменения проходят ревью, история правок видна, а сборка проверяется автоматически. MkDocs не требует базы данных и серверного runtime — только Python на этапе сборки. Готовый сайт состоит из статических файлов, поэтому нагрузка на сервер минимальна, а страницы быстро открываются даже на слабом канале.

Тема Material добавляет к базовому MkDocs поиск с учётом русского языка, удобную навигацию, копирование блоков кода и переключатель светлой и тёмной схемы. Для внутренней документации этого обычно достаточно, а расширять сайт можно плагинами и обычным CSS.

Установка и каркас проекта

Ставьте инструменты в виртуальное окружение, чтобы версии не конфликтовали с системными пакетами. Команда mkdocs new создаёт минимальный проект с одним файлом index.md и конфигурацией.

python3 -m venv .venv
. .venv/bin/activate
pip install --upgrade pip mkdocs-material
mkdocs new docsite && cd docsite

Если хочется запускать mkdocs из любого каталога без активации окружения, подойдёт связка pipx install mkdocs и pipx inject mkdocs mkdocs-material. Для командной работы зафиксируйте зависимости в requirements.txt и обновляйте их осознанно: мажорное обновление темы иногда меняет структуру шаблонов.

Рабочий mkdocs.yml

Конфигурация ниже покрывает типичный проект: русский интерфейс, явное меню, поиск и полезные расширения Markdown. Обратите внимание на site_url: без него неправильно строятся карта сайта и абсолютные ссылки.

site_name: Проект «Вектор»
site_url: https://docs.example.org/
theme:
  name: material
  language: ru
  features:
    - navigation.sections
    - navigation.top
    - content.code.copy
    - search.suggest
  palette:
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      toggle:
        icon: material/weather-sunny
        name: Светлая тема
    - media: "(prefers-color-scheme: light)"
      scheme: default
      toggle:
        icon: material/weather-night
        name: Тёмная тема
plugins:
  - search:
      lang: ru
markdown_extensions:
  - admonition
  - attr_list
  - md_in_html
  - pymdownx.details
  - pymdownx.superfences
  - pymdownx.tabbed:
      alternate_style: true
  - toc:
      permalink: true
nav:
  - Главная: index.md
  - Установка: install.md
  - Настройка: config.md
  - FAQ: faq.md

Меню можно не описывать вручную, а положиться на структуру каталогов, но для небольшого проекта явный nav удобнее: порядок разделов не зависит от алфавита, а лишние черновики не попадают на сайт.

Структура и навигация

Исходники лежат в docs, изображения — в подкаталоге images. Ссылки внутри текста делайте относительными: тогда сайт одинаково работает и в корне домена, и в подкаталоге.

docsite/
├── mkdocs.yml
└── docs/
    ├── index.md
    ├── install.md
    ├── config.md
    ├── faq.md
    └── images/
        └── schema.png

Для предупреждений и примечаний используйте синтаксис admonition. Он читается в исходнике и аккуратно выглядит на сайте.

!!! note "Перед обновлением"
    Снимите резервную копию каталога с данными.

    ```bash
    systemctl status vector
    ```

Вложенные блоки кода внутри admonition требуют отступа в четыре пробела. Если отступ потерян, сайт соберётся, но текст превратится в обычный абзац.

Локальный просмотр и сборка

Во время работы держите запущенным локальный сервер: он пересобирает страницы при сохранении файла. Для доступа с другой машины в той же сети укажите 0.0.0.0, но не оставляйте такой сервер открытым в интернет.

mkdocs serve -a 127.0.0.1:8000
mkdocs serve -a 0.0.0.0:8000
mkdocs build
mkdocs build --strict

Режим --strict превращает предупреждения в ошибку сборки. Именно он ловит ссылки на несуществующие страницы, дубли в меню и проблемы с плагинами. Настройте CI так, чтобы сборка без этого флага не считалась успешной.

Если порт занят другим процессом, сервер не запустится и покажет traceback с адресом. Смените номер через -a 127.0.0.1:8001 или остановите старый процесс. Держать два экземпляра одновременно не нужно: они будут смотреть в один каталог и мешать друг другу.

Публикация

Результат сборки — каталог site. Его достаточно скопировать на веб-сервер. Для nginx важна строка try_files: она отдаёт страницы по «красивым» адресам без расширения .html.

server {
    listen 80;
    server_name docs.example.org;
    root /var/www/docs/site;
    index index.html;
    location / {
        try_files $uri $uri/ $uri.html =404;
    }
}

Обновление сводится к синхронизации каталога. Флаг --delete удаляет на сервере файлы, которых больше нет в сборке, поэтому предварительно убедитесь, что путь указан верно.

rsync -av --delete site/ user@server:/var/www/docs/site/
mkdocs gh-deploy --force

Команда gh-deploy собирает сайт и публикует его в ветку gh-pages. Флаг --force перезаписывает историю этой ветки; для личной документации это нормально, для общего репозитория лучше согласовать схему с командой.

Если сайт отдаётся по HTTPS, не забудьте про сертификат и заголовки кеширования. Статические файлы можно кешировать надолго, но HTML лучше отдавать с коротким сроком жизни, иначе читатель увидит старую версию страницы после обновления.

Проверки и типичные ошибки

Перед публикацией полезно собрать сайт, сохранить журнал и просмотреть его на предмет предупреждений. Локальный HTTP-сервер покажет результат так, как его увидит браузер, включая относительные пути.

mkdocs build --strict 2>&1 | tee build.log
grep -i "warning\|error" build.log
python3 -m http.server 8080 -d site

• Страница отдаёт 404. Проверьте регистр имени файла: на Linux Install.md и install.md — разные файлы.
• Картинка не видна. Ссылка должна быть относительной и указывать на существующий файл внутри docs.
• Поиск не находит русские слова. Убедитесь, что в плагине search указан lang: ru, и пересоберите сайт.
• После обновления темы вёрстка сломалась. Сверьте версии в requirements.txt и читайте примечания к релизу.
• Старые страницы остались на сервере. Синхронизируйте каталог с --delete или очистите site перед сборкой.

Для больших проектов имеет смысл добавить проверку орфографии и линтер Markdown, но начинать стоит со --strict: он бесплатен и закрывает большинство структурных ошибок.

Итог

MkDocs — это предсказуемый способ держать документацию рядом с кодом и публиковать её как обычный статический сайт. Минимальный набор — Python, mkdocs.yml и каталог Markdown-файлов; дальше по желанию добавляются тема, поиск и автоматическая сборка. Главное правило простое: собирайте с --strict, храните исходники в репозитории и не расходитесь с реальностью кода.