MkDocs, Docusaurus и Backstage TechDocs

Три уровня зрелости

Инструменты для документации удобно раскладывать на шкале от «одна команда, один проект» до «сотни команд, тысячи сервисов». Первый уровень закрывает MkDocs. Второй — Docusaurus. Третий — Backstage TechDocs. Это не рейтинг качества — это инструменты под разный масштаб, и выбор зависит от количества сервисов, команд и людей, которые реально пишут документацию.

MkDocs и Material for MkDocs

MkDocs — статический генератор документации на Python, появившийся в 2014 году. Конфигурация — один файл mkdocs.yml, контент — Markdown, сборка — mkdocs build. Локальный сервер с hot reload поднимается через mkdocs serve. Пять минут от установки до работающего сайта.

Material for MkDocs от Мартина Доната (squidfunk) превратил MkDocs из утилитарного движка в инструмент, на котором документация выглядит приличнее многих коммерческих продуктов. Типографика, навигация, поиск, адаптивная вёрстка, тёмная тема, вкладки с кодом на разных языках, admonitions (блоки примечаний, предупреждений, подсказок) — всё это идёт из коробки. Material for MkDocs стал настолько популярным, что в обиходе «MkDocs» и «Material» часто используют как синонимы.

Плагины растягивают функциональность: mkdocs-macros для переменных и шаблонов, mkdocs-mermaid2 для диаграмм, mkdocs-git-revision-date-localized для даты последнего изменения. Экосистема плагинов — одна из сильных сторон проекта.

Ограничения тоже есть. Версионирование документации из коробки не поддерживается (для этого есть плагин mike, но его надо настраивать отдельно). Интернационализация — тоже через плагины, без встроенной поддержки. Для одного проекта на одном языке это норма, но крупный продукт с десятком версий и тремя локалями быстро упирается в потолок.

Важная деталь по статусу. Сам MkDocs не получал обновлений с августа 2024 года. В ноябре 2025 Мартин Донат анонсировал Zensical — генератор нового поколения, совместимый с Material for MkDocs, но построенный на собственном движке. Material for MkDocs перешёл в режим maintenance: критические баги чинятся, новых фич не будет. Под новый проект сегодня стоит присматриваться к Zensical. Тем, кто уже сидит на Material for MkDocs, паниковать не надо — миграция на Zensical задумана как постепенная и обратно совместимая.

Docusaurus

Docusaurus родился в Meta (тогда ещё Facebook) для документации open-source проектов. React, Jest, Relay, Hermes — все на Docusaurus. Версия 2.0, переписанная с нуля, вышла в 2022 году.

Главное отличие от MkDocs — Docusaurus собирает single-page application на React. Переходы между страницами мгновенные, без перезагрузки. Плюс для пользовательского опыта, минус для тех, кому нужна zero-JS документация. Если на фронтенде принципиально избегаются JavaScript-рантаймы, Docusaurus сразу мимо.

В отличие от MkDocs, тут из коробки есть версионирование документации (переключатель между v1, v2, v3 в шапке), интернационализация (полноценный i18n с раздельными директориями для каждого языка) и интеграция с Algolia DocSearch (бесплатная для open-source).

Через MDX в Markdown можно встраивать React-компоненты — интерактивные демо, живые редакторы кода, анимированные диаграммы. Возможностей много, но появляется привязка к React-экосистеме: если команда пишет на Go или Python и React не знает, поддержка кастомных компонентов превращается в головную боль.

Настройка тяжелее MkDocs. Конфигурация — JavaScript-файл (не YAML), стилизация — через CSS-модули или Infima (собственный CSS-фреймворк Docusaurus), деплой — через Node.js. Для JavaScript-команды среда родная; для остальных — лишний слой работы.

Backstage TechDocs

TechDocs — встроенная система документации в Backstage, платформе разработчика от Spotify, разобранной в разделе про IDP. Идея TechDocs такая: документация живёт в репозитории каждого сервиса (docs-as-code), а Backstage собирает её из всех репозиториев и показывает в едином интерфейсе с поиском по всей организации.

Под капотом TechDocs использует MkDocs как движок сборки — в репозитории каждого сервиса лежит mkdocs.yml и папка docs/. На каждый коммит CI собирает документацию через techdocs-cli, кладёт результат в объектное хранилище (S3, GCS, Azure Blob), а Backstage показывает его в своём интерфейсе и применяет стили Material UI. Для команд весь процесс прозрачен: пишут Markdown, остальное делает платформа.

Главная ценность TechDocs не в рендеринге Markdown — это умеет любой генератор. Главное — discoverability: открыл Backstage, нашёл сервис, и тут же рядом видны его документация, API-спецификация, владельцы, зависимости и CI-статус. Документация перестаёт быть изолированным артефактом и становится частью каталога сервисов.

Минусы тоже есть. Сильная привязка к MkDocs (а MkDocs, как уже сказано выше, не обновлялся с августа 2024), ограниченная поддержка плагинов (не все плагины MkDocs работают в контексте TechDocs), стилизация прибита к Material UI Backstage. На GitHub висит issue #32815, где обсуждают эволюцию TechDocs: поддержка Zensical как альтернативного движка либо полный переход на engine-agnostic архитектуру.

Как выбрать

MkDocs (Zensical) — один проект, одна команда, документация нужна за полдня. Стек значения почти не имеет. Версионирование и i18n не требуются.

Docusaurus — JavaScript/TypeScript-стек. Нужны версии документации, несколько языков, интерактивные компоненты. Open-source проект с большим сообществом. Команда готова поддерживать React-компоненты.

Backstage TechDocs — Backstage уже есть или внедряется. Десятки или сотни сервисов. Главная боль — не генерация документации, а её поиск: никто не знает, где лежит документация какого сервиса.

Два практических совета, не зависящих от выбора инструмента. Первый: держите конфигурацию и контент в репозитории рядом с кодом — это docs-as-code, и от движка это не зависит. Второй: начинайте с трёх файлов — README.md, docs/getting-started.md, docs/architecture.md. Инструмент для их рендеринга всегда можно поменять; содержание никуда не денется.