Docusaurus
Метаданные и форматы — конфигурации и данные, Данные и разметка.
Docusaurus
Вселенная IT развёрнута на Docusaurus.
Определение и общая характеристика
Docusaurus представляет собой генератор статических сайтов с открытым исходным кодом, созданный на базе React. Инструмент предназначен для построения документации, блогов и образовательных ресурсов с использованием Markdown и MDX форматов. Система обеспечивает автоматическую генерацию HTML страниц из текстовых файлов разметки с поддержкой интерактивных компонентов React.
Платформа включает встроенные возможности для навигационной структуры, темизации интерфейса, поиска контента, синтаксического подсвечивания кода и адаптивного оформления под мобильные устройства. Процесс сборки преобразует исходные тексты в полный набор статических HTML файлов, CSS стилей и JavaScript скриптов без необходимости работы с серверной частью базы данных при каждом обращении пользователя.
Архитектурная модель Docusaurus
Структура файлов и директорий
Проект на базе Docusaurus организуется по строгой файловой схеме с выделенными областями конфигурации и содержимого. Каждая директория выполняет специфические функции и не пересекается с другими функциональными зонами.
| Директория | Назначение | Тип Содержимого |
|---|---|---|
docs/ | Хранение исходной документации | Markdown (.md), MDX (.mdx) файлы |
src/ | Источники пользовательского кода | React компоненты, CSS, страницы |
static/ | Статические ресурсы | Изображения, шрифты, favicon |
i18n/ | Локализованные настройки | Многоязычные тексты, переводы |
docusaurus.config.js | Конфигурация проекта | JavaScript объекты параметров |
sidebars.js | Настройка навигации | Массивы определений меню |
Все содержимое генерируется из директории docs/, без обращения к внешним системам управления контентом (CMS). Навигация управляется декларативно через файл sidebars.js. Пользовательские элементы интерфейса размещаются в директории src/ с последующим подключением в конфигурационных файлах.
Иерархия обработки файлов
Процесс построения сайта проходит несколько стадий обработки:
- Чтение конфигурационного файла
docusaurus.config.js - Загрузка файлов из директории
docs/ - Парсинг Markdown и MDX синтаксиса
- Применение плагинов и тем оформления
- Генерация таблиц содержания (Table of Contents)
- Сборка финальных HTML документов
- Копирование статических ресурсов в выходную директорию
Каждая страница проходит полный цикл обработки независимо от положения в иерархии навигации. Системы маршрутизации формируют URL автоматически на основе путей файлов внутри docs/.
Трансформация MD/MDX в HTML
Различия между Markdown и MDX
Markdown представляет собой упрощённый язык разметки для форматирования текста. Синтаксис определяет заголовки, списки, цитаты, блоки кода и гиперссылки. Инструменты обработки конвертируют такие документы в валидный HTML код для отображения в браузере.
MDX расширяет возможности Markdown интеграцией экспорта React компонентов внутрь текстового потока. Файл формата MDX содержит стандартные markdown конструкции совместно с импортируемыми элементами интерфейса React. Такая комбинация позволяет создавать интерактивные блоки — таймеры, калькуляторы, карты схем, динамические диаграммы.
// Пример использования компонента внутри MDX файла
<ExternalPlayEmbed example="project/timer" title="Таймер" minHeight={200} playProps={{ seconds: 60 }} />
## Заголовок раздела
Текстовое содержание после интерактивного элемента
Play ITЗагрузка интерактивного демо…
Процесс конвертации
Сборщик Docusaurus выполняет следующие операции трансформации:
- Сканирование всех файлов с расширением
.mdи.mdx - Разбор YAML фронтматеров в начале документа
- Преобразование Markdown синтаксиса в промежуточное представление
- Встраивание компонентов React из импорта в DOM структуру
- Добавление метаинформации о странице в теги head HTML
- Генерация навигационных ссылок между смежными документами
- Формирование полной таблицы содержания в боковой панели
- Создание JSON индексов для системы поиска
Конечный результат представляет собой готовый к развёртыванию набор HTML файлов, соответствующих структуре оригинального источника данных.
Управление навигацией
Файл configuration
Главное меню управляет элементом навигационной панели сайта через свойства объекта конфигурации navbar.items. Каждый элемент списка определяется как объект с идентификатором, типом, меткой и целевой ссылкой.
Код ITЗагрузка примера кода…
Элементы меню поддерживают различные типы — ссылки на документы (doc), боковые панели (docSidebar), выпадающие списки (dropdown), кастомные ссылки (link). Расположение каждого пункта определяют параметры position: left/right/center.
Файл sidebars
Структура сайдбара управляется отдельным файлом sidebars.js. Этот модуль описывает древовидную организацию разделов документации с возможностью группировки, иерархической вложенности и динамического добавления элементов.
Код ITЗагрузка примера кода…
Доступные типы элементов:
| Тип Значение | Описание |
|---|---|
doc | Ссылка на одиночный документ |
category | Группировка связанных документов |
autogenerated | Автоматически сгенерированный список |
html | Кастомный HTML блок |
Флаги collapsed: true/false определяют состояние развернутого вида по умолчанию. Глубина вложенности не ограничивается архитектурой.
Подвал сайта (Footer)
Настройки футера размещаются в объекте footer конфигурационного файла docusaurus.config.js. Параметр links содержит массив ссылок, разбитых по категориям.
Код ITЗагрузка примера кода…
Параметр style определяет цветовую схему: light или dark. Поле copyright задает текст уведомления об авторских правах.
Конфигурационные параметры
docusaurus.config.js
Файл docusaurus.config.js содержит все системные настройки проекта. Объект экспортируется через CommonJS или ECMAScript Modules и может включать множество опций.
Базовая структура:
Код ITЗагрузка примера кода…
Ключевые параметры:
| Параметр | Тип | Назначение |
|---|---|---|
title | string | Полное название сайта |
tagline | string | Краткое описание в шапке |
url | string | Домен размещения |
baseUrl | string | Корневой путь развёртывания |
favicon | string | Путь к иконке браузера |
themeConfig | object | Настройки визуального стиля |
plugins | array | Список установленных расширений |
themes | array | Дополнительные темы |
Theme configuration
Тема оформления определяет визуальные характеристики интерфейса:
- цвета;
- типографику;
- размер шрифта;
- режимы (светлая/тёмная).
Код ITЗагрузка примера кода…
Модификаторы режима оформления:
defaultMode: начальное значение светлого/тёмногоdisableSwitch: флаг отключения переключателя вручнуюrespectPrefersColorScheme: учёт системных настроек пользователя
Технологии рендеринга
Static Site Generation (SSG)
Static Site Generation представляет собой процесс предварительной генерации HTML страниц на этапе сборки проекта. Система читает все исходные документы, применяет шаблоны и создаёт готовые файлы до момента их публичного доступа. Результат сохраняется в статической директории для загрузки на любой веб-сервер.
Преимущества подхода:
- Молниеносная скорость отклика при запросе
- Отсутствие нагрузки на сервер во время просмотра
- Упрощённая масштабируемость инфраструктуры
- Снижение требований к ресурсам хостинга
- Повышенная безопасность через отсутствие бэкенда
Client-Side Hydration
Hydration означает процесс заполнения интерактивной функциональности на клиентской стороне после первоначальной загрузки HTML документа. Браузер получает статический HTML, затем активация JavaScript приводит элементы в рабочее состояние с обработчиками событий и реактивными данными.
Жизненный цикл взаимодействия:
- Сервер отдаёт статический HTML файл
- Браузер парсит и отображает контент
- JavaScript приложение загружается и монтируется
- События кликов получают обработчики
- Реактивные состояния обновляют интерфейс
Такая модель обеспечивает баланс между SEO производительностью и интерактивностью пользовательского опыта.
Server-Side Rendering (SSR)
Server-Side Rendering предполагает выполнение рендеринга на сервере перед отправкой ответа клиенту. Эта техника актуальна для динамических приложений с изменяющимся контентом при каждом запросе.
Docusaurus поддерживает SSG по умолчанию. SSR становится доступным при использовании специализированных плагинов или модификации ядра сборки. Для большинства случаев технической документации достаточно статической генерации.
React-Based архитектура
Компонентная модель
Docusaurus работает поверх фреймворка React, что предоставляет доступ к экосистеме компонентов библиотеки. Каждая часть интерфейса реализуется как независимый функциональный или классический компонент с собственным состоянием и логикой.
Типичная структура компонента:
Код ITЗагрузка примера кода…
Компоненты могут принимать пропсы через JSX атрибуты и передавать данные вниз по дереву рендеринга. Использование хуков React позволяет управлять локальным состоянием без глобальных переменных.
CSS modules
CSS Modules обеспечивают изоляцию стилей внутри конкретного компонента. Классы именуются уникально с добавлением хэш-суффикса при сборке для избежания конфликтов между различными частями интерфейса.
Пример использования:
/* src/pages/index.module.css */
.hero {
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
padding: 80px 20px;
text-align: center;
}
/* src/components/Hero.jsx */
import styles from './index.module.css';
return <div className={styles.hero}>...</div>;
Такая система гарантирует предсказуемость внешнего вида даже при масштабировании проектов.
Плагины и расширения
Prism.js Syntax Highlighting
Плагин подсветки синтаксиса интегрирует библиотеку Prism.js для цветовой маркировки фрагментов кода в различных языках программирования. Каждая статья получает возможность отображать примеры с соответствующей цветовой гаммой.
Конфигурация тем:
Код ITЗагрузка примера кода…
Используемые языки:
- Bash / Shell Script
- C# (.NET Core)
- Java / Kotlin
- JavaScript / TypeScript
- Python
- SQL (PostgreSQL, MS SQL)
- HTML5 / XML / JSON
- PowerShell
Пример блока кода:
// Внутри .md файла
```python
def calculate_sum(a, b):
return a + b
print(calculate_sum(10, 25))
```
Дополнительные плагины
Различные расширения добавляют специализированную функциональность в проект:
| Плагин | Назначение |
|---|---|
docusaurus-preset-classic | Базовая настройка пресета |
@docusaurus/plugin-sitemap | Генерация sitemap.xml |
@docusaurus/preset-classic | Стандартная конфигурация |
docusaurus-plugin-image-zoom | Увеличение изображений |
@docusaurus/theme-search-local | Локальная поисковая система |
@docusaurus/plugin-client-redirects | Перенаправление старых URL |
docusaurus-plugin-typedoc | Автогенерация API документации |
remark-gfm | GitHub Flavored Markdown |
Плагины активируются путём добавления в массив plugins конфигурационного файла и обязательной установки пакетов через менеджер пакетов Node.js.
Front Matter метаданные
Определение фронтматер
Front Matter представляет собой блок YAML информации в начале каждого Markdown файла. Этот раздел содержит метаданные о документе — заголовок, порядок сортировки, тег уровня сложности, ключевые слова для индексации.
Структура фронтматер:
Доступные параметры
Параметры фронтматер используются системой навигации и фильтрации:
| Параметр | Тип | Описание |
|---|---|---|
id | string | Уникальный идентификатор документа |
title | string | Отображаемое название страницы |
sidebar_label | string | Короткий ярлык в боковом меню |
tags | array | Список категорий документа |
complexity | string | Уровень сложности: easy/medium/hard |
lastUpdatedBy | string | Автор последнего изменения |
description | string | Краткое описание для SEO |
author | string | Автор статьи |
date | date | Дата публикации |
Агрегация таблицы содержания
Автоматическая таблица содержания формируется на основе заголовков h2, h3 в теле документа. Дополнительно поддерживается ручной контроль через файл toc.md.
<!-- toc -->
<!-- /toc -->
При обнаружении этого маркера система извлекает все заголовки и строит дерево навигации справа от основного контента.
Правила и ограничения
Ограничения формата документов
Система накладывает ряд требований к структуре файлов для успешной генерации:
- Все документы должны находиться в директории
docs/или подкаталогах - Расширение файлов обязано быть
.mdили.mdx - Фронтматер должен начинаться сразу с первой строки файла без пустых строк между ней и "---"
- Специальные символы в названии файла заменяются нижними подчеркиваниями
- Длина пути документа не должна превышать установленные пределы
Лимиты производительности
Большие объёмы данных влияют на скорость сборки:
- Рекомендуемый максимум количества страниц: до 5000 документов
- Размер одного документа не должен превышать 50 килобайт текста
- Количество изображений лучше минимизировать и компрессировать перед загрузкой
- Использование слишком сложных CSS правил замедляет рендеринг
Требования версии
Необходимые версии инструментов:
- Node.js: ≥ 18.x LTS
- npm: ≥ 9.x
- Docusaurus: версия 3.x или выше
Устаревшие версии Node.js приводят к ошибкам компиляции и недоступности некоторых плагинов.
Установка и развёртывание
Подготовка окружения
Перед началом работы необходимо установить менеджер пакетов и среду выполнения JavaScript. Проверка версий выполняется командой:
node --version
npm --version
Результат должен показывать номера версий, удовлетворяющие требованиям минимум 18.x для Node.js и 9.x для npm.
Инициализация проекта
Создание нового проекта осуществляется через официальный CLI:
npx create-docusaurus@latest my-site classic
cd my-site
Система предложит выбор базового пресета, языка сайта и расположения папок. После завершения запускается локальный dev-сервер для проверки результата.
Команды для работы
Ниже приведён полный список основных операций для управления жизненным циклом проекта.
| Команда | Назначение | Режим |
|---|---|---|
npm install | Установка зависимостей из package.json | Подготовка |
npm start | Локальный dev-сервер с hot-reload | Разработка |
npm run build | Сборка production-версии | Генерация |
npm run serve | Локальный preview собранного сайта | Тестирование |
npm run write | Редактирование документов | Контент |
npm run publish | Публикация на GitHub Pages | Деплой |
Локальный Dev-Сервер
Разработка ведётся на горячем сервере, который автоматически обновляет страницу при изменении файлов:
npm start
После запуска открыть браузер и перейти по адресу http://localhost:3000. Любое изменение в документах немедленно отражается без перезагрузки процесса.
Production сборка
Команда сборки превращает исходники в оптимизированный статический сайт для публикации:
npm run build
Результат сохраняется в директории /build/ или /out/. В этой папке находятся все необходимые файлы для развёртывания на хостинге.
Развёртывание на GitHub Pages
Процесс деплоя включает следующие этапы:
- Настройка Remote репозитория
- Импорт конфига
gh-pages - Вызов скрипта
publish
git remote add origin https://github.com/user/repository.git
npm run deploy
Система автоматически собирает сайт и пушит содержимое в ветку gh-pages.
Структура исходного кода
Прямая организация директорий
my-project/
├── docs/ # Источники документов
│ ├── getting-started.md
│ ├── installation.md
│ └── advanced/
│ └── custom-components.md
├── src/ # Пользовательский код
│ ├── components/ # React компоненты
│ │ ├── HomepageHeader.js
│ │ ├── HomepageTabs.js
│ │ ├── HomepageFeatures.js
│ │ └── AnimatedBackground.jsx
│ ├── css/
│ │ └── custom.css
│ └── pages/
│ ├── index.js
│ └── index.module.css
├── static/ # Статические ресурсы
│ ├── img/
│ └── favicon.ico
├── docusaurus.config.js # Главная конфигурация
├── sidebars.js # Боковое меню
├── package.json # зависимости npm
└── README.md # описание проекта
Кастомизация UI
Интерфейс настраивается через CSS файлы в директории src/css/custom.css и использование CSS Modules.
Custom CSS:
/* src/css/custom.css */
:root {
--ifm-color-primary: #25c2a0;
--ifm-color-primary-dark: rgb(33, 175, 144);
--ifm-color-primary-darker: rgb(31, 165, 136);
--ifm-color-primary-darkest: rgb(26, 136, 112);
--ifm-heading-font-family: 'Roboto', sans-serif;
}
[Данные-theme='dark'] {
--ifm-color-primary: #25c2a0;
}
CSS Modules:
/* src/pages/index.module.css */
.hero {
padding: 80px 20px;
background: linear-gradient(135deg, rgba(37,194,160,1) 0%, rgba(118,75,162,1) 100%);
text-align: center;
}
Главный элемент интерфейса
Компонент HomepageHeader размещает основную информацию на главной странице. Он импортируется в index.js и отображает заголовок, подзаголовок и кнопки действия.
Код ITЗагрузка примера кода…
Интерактивные элементы
Для создания сворачиваемых блоков используется HTML элемент <details> со встроенным атрибутом <summary>. Библиотека clsx применяется для условного присвоения классов CSS.
Использование спойлеров:
<details>
<summary>Раскрыть дополнительные сведения</summary>
Здесь располагается скрытый контент
по нажатию на заголовок
</details>
// src/components/CollapsibleSection.jsx
import clsx from 'clsx';
function CollapsibleSection({ isOpen }) {
const classes = clsx('section', { hidden: !isOpen });
return <div className={classes}>...</div>;
}
Анимация фона
Динамический эффект достигается через SVG с градиентным шумом без использования внешних библиотек анимации.
// src/components/AnimatedBackground.jsx
import React, { useEffect } from 'react';
export default function AnimatedBackground() {
useEffect(() => {
// SVG анимация через CSS transitions
}, []);
return <svg className="animated-bg"></svg>;
}