Docusaurus vs MkDocs vs VitePress: что выбрать команде в 2026

23 марта 2026 г. 14K

Команда выросла, репозиториев стало больше, и в какой-то момент возникает вопрос: на чём писать документацию. Раньше брали Sphinx или GitBook, в 2026 выбор обычно сводится к трём: Docusaurus, MkDocs (с темой Material), VitePress. Все три — статические генераторы, все три про docs-as-code, все три бесплатные. Различия — в стеке, философии и мелочах, которые становятся важными на длинной дистанции.

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

Коротко о каждом

Docusaurus — генератор от Meta. React под капотом, TypeScript-friendly, MDX из коробки. Проект — сайт документации с блогом, версионированием, мультиязычностью и кастомными React-компонентами в страницах.

MkDocs с темой Material — Python, чистый Markdown, рендер на стороне сборки в HTML. Тема Material де-факто стандарт, она настолько богата фичами, что часто люди говорят «MkDocs», подразумевая «MkDocs Material».

VitePress — генератор от автора Vue, на Vite. Markdown с возможностью встраивать Vue-компоненты, очень быстрая сборка, минималистичный дефолтный вид.

Стек и зависимости

Это первое, что фильтрует выбор. Команда не любит держать зоопарк рантаймов.

Docusaurus — Node.js, npm/yarn/pnpm. Зависимостей много (всё-таки React-фреймворк), сборка прогревается несколько секунд.
MkDocs — Python 3, pip или poetry. Зависимостей мало, сборка быстрая.
VitePress — Node.js, как Docusaurus, но дерево зависимостей значительно скромнее. Сборка очень быстрая.

Если у тебя всё на JS/TS — Docusaurus или VitePress впишутся в существующий пайплайн. Если основной стек Python (бэкенд на Django/FastAPI, ML-проект) — MkDocs логичнее: команда уже знает pip, локально запускается без Node.js.

Смешанная команда — компромисс. На моей практике для документации API на FastAPI всегда брала MkDocs, потому что он живёт в том же репозитории и собирается тем же CI без отдельного Node-стека.

Markdown vs MDX vs расширенный Markdown

Самое заметное различие в опыте автора.

MkDocs Material — чистый Markdown с расширениями через плагины pymdown-extensions: admonitions (выделенные блоки «Note», «Warning»), вкладки, аккордеоны, диаграммы Mermaid, footnotes. Синтаксис — нестандартный Markdown, но в нём нет JS, только разметка.

!!! warning "Осторожно"
    Этот эндпоинт удаляет данные без подтверждения.

=== "curl"
    `curl -X DELETE /users/123`

=== "Python"
    `requests.delete('/users/123')`

Docusaurus — MDX. Это Markdown, в который можно встраивать React-компоненты. Очень гибко: интерактивные демки, сложные виджеты, переиспользуемые блоки. Минус — это перестаёт быть просто Markdown, и автор должен немного знать React.

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Установка

<Tabs>
  <TabItem value="npm" label="npm">
    `npm install superlib`
  </TabItem>
  <TabItem value="yarn" label="yarn">
    `yarn add superlib`
  </TabItem>
</Tabs>

VitePress — Markdown с Vue-компонентами через :::-блоки и прямой вставкой. Похоже на Docusaurus по идее, но синтаксис ближе к чистому Markdown.

::: warning
Этот эндпоинт удаляет данные без подтверждения.
:::

::: code-group
``` bash [curl]
curl -X DELETE /users/123
```
``` python [Python]
requests.delete('/users/123')
```
:::

Когда документацию пишут разработчики, MDX и встраивание Vue работают. Когда пишут технические писатели или менеджеры — чистый Markdown в MkDocs выигрывает: ниже порог входа, меньше шансов сломать страницу.

Скорость сборки и dev-сервера

На малом проекте (50 страниц) разницы не видно. На большом (500+ страниц, на которые я ходила в одном проекте API-доков) — заметна.

VitePress — самая быстрая сборка благодаря Vite и esbuild. Hot reload на изменении страницы — миллисекунды.
MkDocs — сборка средняя, но dev-сервер с mkdocs serve работает шустро, потому что инкрементально перерендерит только изменённую страницу.
Docusaurus — самая тяжёлая. На 500 страницах с MDX холодная сборка занимает минуту-две, hot reload секунды. Для команды это значит «писатель открывает редактор раз и держит сервер день».

Версионирование и i18n

Если ты пишешь библиотеку с несколькими major-версиями документации одновременно, или нужен мультиязычный сайт.

Docusaurus — лучшее в этой категории. Версионирование встроено: одна команда docusaurus docs:version 2.0 делает снапшот текущих доков, и сайт показывает выбор версий. i18n — отдельный i18n/ каталог с переводами по языкам, переключатель в UI из коробки.

MkDocs Material — i18n решается через mike для версий и mkdocs-static-i18n для языков. Работает, но как сборка из плагинов, а не цельная фича.

VitePress — версионирование делается вручную через папки и роутинг. i18n есть в виде locales, но это не настолько проработано, как в Docusaurus.

Если нужны 3+ версии документации одновременно или больше двух языков — Docusaurus. Если одна версия и максимум русский+английский — оба остальных подойдут.

Поиск

Поиск по доке должен работать. Пользователи открывают доку, вбивают «error 401» и ожидают увидеть результат.

MkDocs Material — встроенный клиентский поиск работает из коробки. Lunr/MiniSearch в фоне, индекс собирается на сборке. На 1000 страниц всё ещё работает приемлемо.
Docusaurus — встроенного локального поиска нет. Стандартное решение — Algolia DocSearch (бесплатный для open-source, но требует регистрации) либо плагин @easyops-cn/docusaurus-search-local. Из коробки — никак.
VitePress — встроенный локальный поиск есть, базовый. Для серьёзного — также Algolia.

На корпоративном сайте без выхода в Algolia (закрытая дока, например) MkDocs Material выигрывает. На публичной open-source — Algolia покрывает всех троих.

Кастомизация и тема

Когда нужно «сделать сайт похожим на наш бренд».

MkDocs Material — кастомизация ограничена темой Material. Цвета, шрифты, лого меняются легко. Глубже — переопределение шаблонов через Jinja, это работает, но руки нужны.
Docusaurus — полностью кастомизируемая тема через swizzling: ты копируешь любой компонент в свой проект и переписываешь. Гибко максимально, но требует знания React.
VitePress — кастомизация через Vue-компоненты темы, похоже на Docusaurus, но проще, если уже знаешь Vue.

Если нужен «наш собственный сайт» с лендингом, портфолио, документацией в одном — Docusaurus или VitePress. Если документация — это документация, и достаточно поменять цвета и логотип — MkDocs Material.

Генерация из OpenAPI

Часть моей работы — рендерить документацию API из OpenAPI-спеки. Все три умеют.

MkDocs — через плагины: mkdocs-render-swagger-plugin, neoteroi-mkdocs. Работают по-разному, у каждого свои нюансы.
Docusaurus — docusaurus-plugin-openapi-docs от Pally, рендер через ReDoc или собственный. Очень мощный, генерирует страницы для каждого эндпоинта.
VitePress — встроенного нет, обычно встраивают ReDoc или Swagger UI как отдельную страницу.

Для API-first документации Docusaurus с openapi-docs — самый зрелый путь. Он делает дерево страниц по эндпоинтам, кросс-ссылки, нормальную навигацию.

Деплой

Все три — статические сайты, деплоятся на любой хостинг для статики: GitHub Pages, Netlify, Vercel, Cloudflare Pages, S3+CloudFront, свой nginx.

Размер артефакта:

MkDocs — самый компактный, чистый HTML+CSS+минимум JS.
VitePress — компактный, Vue-рантайм небольшой.
Docusaurus — самый тяжёлый, бандл React-приложения. На медленном интернете заметно.

Для внутренней корпоративной документации, где разница в мегабайтах не важна, это не аргумент. Для публичной с миллионами визитов — стоит думать.

Когда что выбрать

Бери MkDocs Material, если:

Стек проекта Python.
Документацию пишут не только разработчики (PM, аналитики, DevOps).
Нужны admonitions, табы, диаграммы из коробки без MDX/Vue.
Хочется минимум зависимостей и быструю сборку.
Поиск нужен локально, без внешних сервисов.

Бери Docusaurus, если:

Стек JS/TS, команда уже работает с React.
Нужно версионирование документации (две и больше major-версий одновременно).
Нужно несколько языков с полноценным переключателем.
Основа — это документация API из OpenAPI с богатым рендером.
Сайт совмещает блог, лендинг, документацию.

Бери VitePress, если:

Стек Vue или просто JS/TS, нет нагрузки на версионирование/i18n.
Нужен максимально быстрый dev-сервер и сборка.
Документация компактная, без сложных виджетов.
Хочется минималистичный вид без долгой настройки.

Что не повлияет на выбор сильно

Пара вещей, на которые иногда смотрят, но они не должны быть решающим фактором:

Звёзды на GitHub. Все три популярны, активно поддерживаются, ни один не «брошен».
Дата последнего релиза. Релизы у всех регулярные.
«Кажется красивее». Внешний вид кастомизируется в любом из них; «дефолтный VitePress самый стильный» — это вкусовщина, через месяц использования вы прикрутите свои цвета.

Стоимость переключения

Markdown в одном генераторе обычно не работает в другом без правок: каждая платформа добавляет свой синтаксис для табов, admonitions, диаграмм. Перенос 200 страниц с MkDocs на Docusaurus — это не «сменить генератор за вечер», а спринт с переписыванием спецсинтаксиса.

Поэтому стартовое решение — это не пробный шар, а инвестиция на годы. Потратить день на сравнение и пилот на 5-10 страницах в каждом инструменте — экономически выгоднее, чем «возьмём А и потом мигрируем».

Что в итоге выбрала бы я

На последних трёх проектах — два MkDocs Material и один Docusaurus. MkDocs выбирала, когда команда смешанная (разработчики + продакты пишут доки) и стек либо Python, либо безразличен. Docusaurus — когда был SDK на TypeScript с тремя версиями и два языка перевода. VitePress отлично пошёл бы на личный пет-проект или на маленькую публичную либу с компактной докой; на корпоративный продукт — пока не выбирала.

Главное — не пытайся выбрать «лучший». Лучшего нет. Есть тот, что ляжет на твой стек, темп, и команду без ежедневной борьбы. Если генератор тормозит, требует знаний, которых нет, или жрёт время на каждой сборке — он не подходит, какой бы крутой ни был на бумаге.