Что это такое
Docusaurus — инструмент для создания сайтов документации и страниц проектов. Он объединяет Markdown/MDX, маршруты, блог, версионирование документации, поиск, темы и React-компоненты в готовую систему для публичного сайта.
Проект появился из практической нужды: командам с открытым кодом и продуктовым библиотекам нужен сайт, который проще поддерживать, чем полностью самописную систему, но гибче, чем простой набор статичных страниц.
Как устроен сайт на Docusaurus
Обычно материалы живут в папках с документацией и блогом. Разработчик пишет страницы в Markdown или MDX, задает боковое меню, настраивает тему и получает сайт с навигацией, ссылками, подсветкой кода и версионированием.
React важен там, где обычного Markdown мало. В документацию можно вставлять компоненты, интерактивные примеры, вкладки, предупреждения и элементы, которые ведут себя как часть приложения.
Страница документации
Пример показывает типичный материал Docusaurus: метаданные страницы, заголовок, текст и небольшой фрагмент команды рядом.
---
title: Quick start
sidebar_position: 1
---
# Quick start
Install the package and run the local documentation site.
```bash
npm install
npm run start
```Почему он популярен
Docusaurus снимает с команды много скучной работы: маршруты, боковое меню, сборка, версии документации, оформление кода, блог и базовая структура уже продуманы. Это особенно полезно проектам, где документация должна развиваться вместе с кодом.
Важна и привычная модель хранения. Документация лежит в репозитории рядом с проектом, проходит ревью, меняется в pull request и версионируется так же, как код.
Сильные стороны
Главная сильная сторона — баланс между готовностью и гибкостью. Можно быстро получить аккуратный сайт, но при необходимости расширять его React-компонентами и собственной темой.
Docusaurus хорошо подходит проектам с несколькими версиями документации. Пользователь может читать материалы для текущего релиза, а команда сохраняет старые версии для тех, кто еще не обновился.
Ограничения
Если нужен совсем простой сайт из пары страниц, Docusaurus может быть тяжелее, чем обычный статический генератор. Его преимущества раскрываются, когда есть документация, блог, навигация и долгий срок жизни проекта.
Гибкость React также требует дисциплины. Если каждую страницу превращать в уникальный интерфейс, документация теряет единый стиль и становится сложнее в поддержке.
Кому подойдет
Docusaurus хорошо подходит библиотекам, фреймворкам, внутренним платформам, образовательным материалам и любым проектам, где документация — не приложение к коду, а часть продукта.
Для команды это способ держать тексты ближе к разработке: изменения API, примеры и объяснения проходят тот же процесс, что и изменения в коде.