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 для отображения даты последнего изменения. Экосистема плагинов — одна из сильных сторон MkDocs.

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

Важное обновление: MkDocs как проект не получал обновлений с августа 2024 года. Мартин Донат в ноябре 2025 анонсировал Zensical — генератор нового поколения, совместимый с Material for MkDocs, но построенный на собственном движке вместо 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 проектов).

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

Настройка Docusaurus сложнее, чем 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-статусом. Документация перестаёт быть изолированным артефактом и становится частью каталога сервисов.

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

Как выбрать

MkDocs (Zensical) — один проект, одна команда, нужна документация за полдня. Python-стек или стек не важен. Нет требований к версионированию и интернационализации.

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

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

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