Создание сайтов документации с помощью Docusaurus

Вам нужен сайт документации для вашей библиотеки, фреймворка или SaaS-продукта. Вы хотите, чтобы он был статическим, быстрым и удобным в обслуживании, без необходимости создавать всё с нуля. Docusaurus v3 отлично справляется с этой задачей — это зрелый статический генератор сайтов на базе React, который из коробки поставляется с версионированием, интеграцией поиска и поддержкой MDX.

Это руководство охватывает архитектуру и практическую настройку сайта документации на Docusaurus, фокусируясь на концепциях, которые остаются стабильными в рамках минорных релизов.

Базовая архитектура сайта документации на Docusaurus

Docusaurus организует контент в три различных типа контента:

Документация (Docs) размещается в директории /docs. Это ваши основные страницы документации, которые отображаются с автоматической навигацией в сайдбаре и поддержкой версионирования. Каждый Markdown или MDX файл становится страницей.

Блог-посты размещаются в /blog. Они хорошо подходят для журналов изменений, анонсов релизов или туториалов, привязанных ко времени.

Страницы (Pages) в /src/pages — это отдельные React-компоненты или MDX-файлы для кастомных лендингов, разделов “О нас” или любого контента вне структуры docs/blog.

Модель сайдбара и версионирования заслуживает внимания. Docusaurus автоматически генерирует сайдбары из структуры ваших папок, или вы можете определить их явно в sidebars.js. Когда вы создаёте версию, он делает снимок текущей документации в versioned_docs/, позволяя пользователям получать доступ к документации для старых релизов.

Настройка Docusaurus v3: начало работы

Современный скаффолдинг поддерживает npm, Yarn, pnpm и Bun. Выберите тот, который использует ваша команда:

npx create-docusaurus@latest my-docs classic

Пресет classic включает плагин документации, плагин блога и дефолтную тему — достаточно для большинства сайтов документации для разработчиков. Docusaurus v3 требует Node.js 20 или выше для локальной разработки и CI.

После скаффолдинга структура вашего проекта выглядит так:

my-docs/
├── docs/
├── blog/
├── src/
│   ├── components/
│   ├── css/
│   └── pages/
├── static/
├── docusaurus.config.js
└── sidebars.js

Файл docusaurus.config.js управляет метаданными сайта, конфигурацией темы, навигационной панелью, футером и опциями плагинов. Этот единственный файл обрабатывает большую часть кастомизации без необходимости трогать React-код.

MDX-документация: написание контента

Docusaurus v3 использует MDX v3, который строже предыдущих версий. Это важно, если вы мигрируете с v2 — MDX v3 требует правильный синтаксис JSX и не будет молча игнорировать некорректные компоненты.

Каждый файл документации поддерживает frontmatter для метаданных:

---
id: getting-started
title: Getting Started
sidebar_position: 1
---

# Getting Started

Your content here. You can import React components directly.

Вы можете встраивать React-компоненты, использовать диаграммы Mermaid и включать интерактивные блоки кода. Алиас @site указывает на корень вашего проекта для импортов.

Для диаграмм включите плагин Mermaid в вашей конфигурации:

// docusaurus.config.js
module.exports = {
  markdown: {
    mermaid: true,
  },
  themes: ['@docusaurus/theme-mermaid'],
}

Темизация и кастомизация

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

Для визуальной кастомизации переопределите CSS-переменные в src/css/custom.css. Тема использует Infima под капотом, поэтому вы настраиваете дизайн-токены, а не пишете стили компонентов:

:root {
  --ifm-color-primary: #2e8555;
  --ifm-code-font-size: 95%;
}

Более глубокая кастомизация использует “swizzling” — извлечение компонентов темы для их модификации. Запустите npx docusaurus swizzle, чтобы увидеть доступные компоненты. Извлекайте только то, что вам нужно, так как извлечённые компоненты требуют ручных обновлений при апгрейде Docusaurus.

Интеграция поиска

Большинство продакшн-сайтов на Docusaurus используют Algolia DocSearch. Подайте заявку на бесплатную программу, если ваша документация публичная, или разверните краулер самостоятельно для приватной документации.

Конфигурация находится в themeConfig:

// docusaurus.config.js
module.exports = {
  themeConfig: {
    algolia: {
      appId: 'YOUR_APP_ID',
      apiKey: 'YOUR_SEARCH_API_KEY',
      indexName: 'YOUR_INDEX_NAME',
    },
  },
}

DocSearch v4 также поддерживает Algolia AskAI, который добавляет опциональный разговорный поиск поверх стандартного поискового интерфейса и настраивается как часть той же интеграции Algolia.

Развёртывание

Docusaurus собирает статические HTML, CSS и JavaScript в директорию /build. Подходит любой статический хостинг: Vercel, Netlify, GitHub Pages, Cloudflare Pages или ваш собственный CDN.

npm run build

Результат — стандартный статический сайт, не требующий серверного рантайма. Настройте ваш хостинг-провайдер на обработку клиентской маршрутизации, отдавая index.html для неизвестных путей.

Что нужно знать для продакшна

Несколько практических замечаний по поддержке сайта документации для разработчиков:

• Версионирование добавляет сложность. Используйте версии только когда пользователям действительно нужен доступ к старой документации. Многие проекты прекрасно обходятся одной “текущей” версией.
• Строгость MDX выявляет реальные баги. Если миграция с v2 ломает страницы, ошибки обычно указывают на реальные проблемы с JSX, которые стоит исправить.
• Время сборки масштабируется с контентом. Большие сайты выигрывают от инкрементальных сборок в CI и кеширования node_modules.

Заключение

Docusaurus берёт на себя инфраструктуру, чтобы вы могли сосредоточиться на написании хорошей документации. Основа на React означает, что фронтенд-команды могут глубоко кастомизировать при необходимости, в то время как дефолтные настройки работают достаточно хорошо, что многие сайты запускаются вообще без касания React-кода. Начните с пресета classic, добавляйте плагины по мере появления требований и сопротивляйтесь желанию чрезмерно кастомизировать до того, как контент вашей документации станет солидным.

Часто задаваемые вопросы

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers. Check our GitHub repo and join the thousands of developers in our community.