Перейти к основному содержимому

docusaurus.config.js

Что такое Docusaurus​

Docusaurus — open-source фреймворк от Meta для сайтов с упором на документацию и контент. Он собирает Markdown и MDX из папки docs/ в статический сайт на React, с готовой темой, навигацией и dev-сервером. По духу это микрофреймворк поверх экосистемы JavaScript — Webpack или Rspack режут JS на чанки, React даёт SPA-навигацию после первой загрузки.

"Вселенная IT" использует Docusaurus 3.10 (ветка future.v4). Официальная документация фреймворка — на docusaurus.io; здесь разбирается проектный файл конфига и связь с архитектурой.

Файл docusaurus.config.js в корне репозитория — единая точка настройки сайта. Docusaurus читает его при start, build и swizzle. Здесь задаются URL, плагины, тема, редиректы, remark-цепочка для markdown и кастомные правила webpack.

Как конфиг связан со сборкой​

ЭтапКомандаЧто читает из config
Devnpm startпресеты, plugins, clientModules, env для faster
Prodnpm run buildто же + url/baseUrl для Sitemap и метаданных
Темаnpm run swizzleпути к @docusaurus/theme-classic

См. также package.json и стек и HTTP как основу веб-интеграций.

Базовые поля​

module.exports = {
  title: 'Вселенная IT',
  tagline: 'Единый и ультимативный гайд по IT',
  favicon: 'img/favicon.ico',

  url: 'https://spirzen.ru',
  baseUrl: '/',

  organizationName: 'Spirzen',
  projectName: 'it-knowledge-base',
  trailingSlash: false,

  onBrokenLinks: 'warn',
  // ...
};
ПолеЗначение в проектеЗачем
url + baseUrlКанонический домен, корень /Sitemap, Open Graph, абсолютные ссылки
trailingSlash: falseURL вида /about/projectЕдиный стиль без завершающего слэша — см. адресную строку
onBrokenLinks: 'warn'Битые ссылки дают предупреждениеПри ~3000 статей идеальная ссылочная целостность достигается постепенно

title и tagline попадают в метаданные страницы и влияют на сниппеты в поисковиках — рядом по смыслу SEO-оптимизация.

customFields — URL внешних сервисов​

const codeExamplesUrl =
  process.env.IT_CODE_EXAMPLES_URL ??
  (isProdBuild ? 'https://code.spirzen.ru' : 'http://localhost:4321');

const playExamplesUrl =
  process.env.IT_PLAY_URL ?? (isProdBuild ? 'https://play.spirzen.ru' : 'http://localhost:4322');

customFields: {
  codeExamplesUrl,
  playExamplesUrl,
},

customFields — произвольные поля, доступные в React через useDocusaurusContext().siteConfig.customFields. Так конфиг передаёт URL code/play в embed-компоненты без хардкода в src/components/.

На локальном сервере (npm start, порт 3000) embed-сервисы по умолчанию смотрят на порты 4321 и 4322.

IT_CODE_EXAMPLES_URL=http://127.0.0.1:4321 IT_PLAY_URL=http://127.0.0.1:4322 npm start

clientModules​

clientModules — массив путей к JS-модулям, которые браузер выполняет на каждой странице до основного React-дерева.

clientModules: [
  require.resolve('./src/clientModules/itThemeStorageGuard.js'),
  require.resolve('./src/clientModules/itDesignThemeInit.js'),
  require.resolve('./src/clientModules/limitRoutePrefetch.js'),
],
МодульНазначение
itThemeStorageGuardЧистит повреждённые значения theme* в localStorage (защита от цикла color mode)
itDesignThemeInitВосстанавливает data-design при клиентской навигации
limitRoutePrefetchОграничивает prefetch тяжёлых route

Дополнительно inline-скрипт в плагине it-design-theme-inject ставит data-design до первой отрисовки (без FOUC). Подробнее — Темы и стили и хранение в браузере.

Пресет classic​

Пресет — готовый набор плагинов и настроек одной строкой. @docusaurus/preset-classic включает docs, блог (у нас выключен), тему classic и базовый webpack-пайплайн.

presets: [
  [
    'classic',
    {
      docs: {
        sidebarPath: './sidebars.js',
        routeBasePath: '/',
        numberPrefixParser: false,
        showLastUpdateTime: true,
        remarkPlugins: [
          require('./src/remark/wikiLink.js'),
          require('./src/remark/lazyMdxDemoImports.js'),
        ],
      },
      blog: false,
      theme: {
        customCss: [
          './src/css/custom.css',
          './src/css/it-design-code-overrides.css',
        ],
      },
    },
  ],
],

Ключевые решения Пресета classic.

sidebarPath указывает на файл бокового меню; showLastUpdateTime показывает дату правки из Git на странице статьи.

Плагины​

Плагин в Docusaurus расширяет сборку — lifecycle-хуки, дополнительные route, правки webpack, inject в HTML.

@docusaurus/plugin-client-redirects​

Сохраняет закладки после переименования папок энциклопедии.

createRedirects(existingPath) {
  const fromGenerated = docLegacyRedirects[existingPath] ?? [];
  const fromManual = slugRedirects[existingPath] ?? [];
  const fromEncFolders = fromEncyclopedia ?? [];
  const merged = [...fromGenerated, ...fromManual, ...fromEncFolders];
  // ...
}

Три источника редиректов.

  1. docLegacyRedirects.json — автогенерация (npm run docs:redirects).
  2. slugRedirects — ручная карта в конфиге (C language, design patterns, переименования папок).
  3. ENCYCLOPEDIA_FOLDER_RENAMES — обратные редиректы со старых путей с кириллицей в имени папки.

it-konva-canvas-fallback​

resolve: { fallback: { canvas: false } }

Библиотека Konva тянет модуль canvas для Node. В браузерной сборке resolve.fallback с canvas: false отключает лишний полифилл. См. Canvas 2D.

it-async-chunks​

Настраивает splitChunks для клиента — отдельные vendor-чанки React, Docusaurus, Prism, Mermaid; async-чанки для embed-компонентов и остальной папки src/components/.

it-design-theme-inject​

В <head> — inline-скрипт data-design, dns-prefetch и preconnect на play/code (ранний fetch DNS/TCP). См. CDN и быстрая доставка.

themeConfig​

Секция themeConfig настраивает визуальную тему @docusaurus/theme-classic — navbar, footer, Prism, docs sidebar.

Документация и подсветка кода​

docs: {
  sidebar: { hideable: true },
},
prism: {
  additionalLanguages: [
    'bash', 'c', 'cpp', 'csharp', 'docker', 'go', 'java',
    'kotlin', 'php', 'powershell', 'python', 'rust', 'sql', 'yaml',
  ],
},

Prism — движок подсветки блоков кода в статьях. Список additionalLanguages расширяет языки поверх встроенных — иначе fenced-блок ```rust останется без раскраски.

items: [
  { type: 'docSidebar', sidebarId: 'docsSidebar', label: 'Энциклопедия' },
  { to: '/encyclopedia/1-basics/1-03-dorozhnaya-karta-izucheniya/101', label: 'Указатель' },
  { type: 'custom-docSearch', position: 'right' },
],
  • docSidebar + sidebarId: 'docsSidebar' — пункт меню, привязанный к боковому дереву из sidebars.js.
  • custom-docSearch — кастомный тип navbar; в swizzle ComponentTypes.js он рендерит DocSearchBar.

Поиск Algolia​

Блок закомментирован. Вместо SaaS-поиска Algolia — свой JSON-индекс и DocSearchBar (Данные и скрипты).

Mermaid​

markdown: { mermaid: true },
themes: ['@docusaurus/theme-mermaid'],

В статьях можно писать блоки ```mermaid без импорта — диаграммы рендерятся на клиенте. Теория диаграмм — Основы диаграмм и моделирования.

future и Windows​

const isWindowsDev = process.platform === 'win32' && process.env.NODE_ENV !== 'production';
const useFasterBundler =
  process.env.IT_DOCUSAURUS_FASTER === '1' || !isWindowsDev;

future: {
  v4: true,
  faster: useFasterBundler,
},

Docusaurus 4 + опциональный Rspack bundler (@docusaurus/faster, флаг dev faster). На Windows dev faster выключен по умолчанию из-за лимита открытых файлов (EMFILE) при тысячах MDX. Включение — IT_DOCUSAURUS_FASTER=1.

Сборщик описан в контексте Webpack и Vite.

i18n​

i18n: {
  defaultLocale: 'ru',
  locales: ['ru'],
},

i18n (internationalization) — встроенная локализация Docusaurus (отдельные папки i18n/, переключатель языка, дубли route). Сейчас сайт одноязычный (русский); блок оставлен для возможного расширения. См. локализацию в Windows как смежную тему кодировок и символов.

Типичные задачи​

ЗадачаГде менять
Добавить язык в подсветку PrismthemeConfig.prism.additionalLanguages
Новый пункт navbarthemeConfig.navbar.items
Редирект со старого URLslugRedirects или npm run docs:redirects
Подключить глобальный CSSpresets.classic.theme.customCss
Изменить URL code/playcustomFields или env IT_CODE_EXAMPLES_URL / IT_PLAY_URL
Новый remark-плагинpresets.classic.docs.remarkPlugins
Включить Rspack на WindowsIT_DOCUSAURUS_FASTER=1

Полезные команды Docusaurus​

npm run docusaurus -- --help
npm run swizzle @docusaurus/theme-classic DocItem/Layout
npm run clear

Swizzle уже выполнен для основных компонентов — правки темы идут в src/theme/. Отладка в браузере — вкладка Network ( fetch, чанки ), Application (localStorage).

Глоссарий терминов конфигурации​

Краткие определения в контексте docusaurus.config.js. Якоря — для ссылок из других глав.

URL​

Адрес ресурса в сети (https://spirzen.ru/encyclopedia/intro). В config поля url и baseUrl задают канонический хост и путь. См. HTTP-справочник и адресную строку.

Плагин​

Модуль, расширяющий Docusaurus (редиректы, mermaid, кастомный webpack). Подключается в plugins: [] или внутри пресета.

Тема​

Пакет UI (navbar, sidebar, typography) — @docusaurus/theme-classic. Настраивается через themeConfig и swizzle. Стили — Темы и стили.

Webpack​

Сборщик модулей — склеивает JS, CSS, assets в бандл и чанки. В Docusaurus 3 может быть заменён на Rspack. См. экосистему JS.

Корень​

baseUrl: '/' — сайт отдаётся с домена без префикса /docs. Страницы энциклопедии — /encyclopedia/....

Sitemap​

XML-карта URL для поисковых роботов; генерируется при build из url + baseUrl. Рядом по смыслу SEO.

Open Graph​

Набор meta-тегов (og:title, og:image) для превью ссылки в соцсетях и мессенджерах. Docusaurus подставляет их из title, description, slug.

Абсолютные ссылки​

URL с хостом (https://spirzen.ru/...). Нужны в Sitemap, RSS, canonical, шаринге.

Битые ссылки​

Ссылка на несуществующий route. onBrokenLinks: 'warn' сообщает при сборке, но не останавливает её.

customFields​

Произвольные ключи в config, доступные в React. В проекте — codeExamplesUrl, playExamplesUrl.

Порт​

Число TCP-сокета (локальный сервер 3000, code 4321, play 4322). Задаётся URL или env.

Локальный сервер​

docusaurus start — dev-сервер с hot reload на http://localhost:3000. Статика продакшена — docusaurus serve после build.

clientModules​

Глобальные JS-модули, выполняемые в браузере на каждой загрузке до React.

Скрипт​

Фрагмент JS — файл модуля, inline-блок в <head> или npm-скрипт в package.json.

Страница​

Один URL сайта — статья docs, главная из src/pages/, generated-index категории.

Браузер​

Клиентское ПО (Chrome, Firefox…), исполняет HTML/CSS/JS. См. движки браузеров.

React​

Библиотека UI; Docusaurus строит на ней интерактивный слой поверх статического HTML. Справочник.

localStorage​

Постоянное хранилище в браузере для ключей вроде theme, it-universe-design. См. хранение данных.

Цикл color mode​

Зацикливание переключателя light/dark из-за битого значения в localStorage. Лечит itThemeStorageGuard.

data-design​

HTML-атрибут data-design на <html> — выбранная палитра дизайна. Inject-плагин и client modules держат его согласованным.

Клиентская навигация​

Переход между route без полной перезагрузки — SPA. Docusaurus подгружает JS-чанк следующей страницы.

fetch и prefetch​

fetch — загрузка ресурса по сети. prefetch — заблаговременная подгрузка route; limitRoutePrefetch отключает её для тяжёлых разделов. См. HTTP.

inline​

Код или разметка прямо в HTML (не отдельный файл) — например скрипт data-design в <head>.

inject​

Вставка тегов в HTML на этапе сборки — хук плагина injectHtmlTags().

Отрисовка​

Paint/layout в браузере — момент, когда пользователь видит стилизованную страницу.

FOUC​

Flash Of Unstyled Content — краткое "мигание" до применения CSS/темы. Снижается ранним inline-скриптом data-design.

Пресет​

Готовый bundle плагинов и настроек — @docusaurus/preset-classic.

Пресет classic​

Стандартный пресет Docusaurus — docs, опциональный блог, тема, CSS. Используется в проекте целиком.

route​

Маршрут приложения — соответствие URL ↔ React-страница. Задаётся файлами в docs/, src/pages/, плагинами.

Префикс​

Начало имени файла или пути (1-03- в 1-03-dorozhnaya-karta). numberPrefixParser: false — Docusaurus не вырезает его из URL автоматически.

require​

CommonJS-импорт модуля в Node (require('./sidebars.js')). В config и remark-плагинах — обычный способ подключить локальный файл. См. модули в JS.

blog​

Плагин блога Docusaurus (@docusaurus/plugin-content-blog). В проекте blog: false — новости и хронология ведутся в docs/.

slug​

Часть URL статьи; задаётся в frontmatter (slug: /encyclopedia/...) или выводится из пути файла.

docs​

Плагин @docusaurus/plugin-content-docs — папка docs/, sidebar, версии. Ядро энциклопедии.

wiki-ссылки​

Синтаксис [[термин]] в markdown; обрабатывает remark-плагин wikiLink.js и индекс wikiLinkIndex.json.

lazy-import​

Отложенный импорт компонента — import() + обёртка lazyDemoInView. В MDX включается плагином lazyMdxDemoImports.js.

Закладки​

Сохранённые пользователем URL. Редиректы сохраняют старые пути после переезда папок.

Папки энциклопедии​

Иерархия docs/encyclopedia/... — разделы, подразделы, статьи. Переименование ломает старые URL без plugin-client-redirects.

Автогенерация​

Скрипты npm run docs:* создают JSON (редиректы, поиск, wiki) перед сборкой.

Конфиг​

docusaurus.config.js — главный файл настроек, экспортирует module.exports = { ... }.

Кириллица​

Буквы русского алфавита в путях и заголовках. Старые папки энциклопедии с кириллицей в имени заменены латинскими slug; редиректы в config сохраняют старые закладки.

resolve​

Секция webpack — как искать модули (resolve.fallback подменяет Node-модули в браузере).

canvas​

Node-модуль эмуляции Canvas 2D; для браузера не нужен — отключён в fallback.

Konva​

2D-библиотека поверх canvas; тянет canvas в сборке — отсюда плагин it-konva-canvas-fallback.

fallback​

Запасной вариант resolve — "если модуль не найден в браузере, подставь false/пустышку".

Полифилл​

Код, эмулирующий API среды (Node canvas в browser bundle). Проект сознательно отключает лишние полифиллы.

async​

Асинхронная загрузка — чанк подтягивается после первого экрана (chunks: 'async' в splitChunks).

Чанк​

Фрагмент JS-бандла, подгружаемый отдельным запросом.

vendor-чанки​

Чанки из node_modules — vendor-react, vendor-docusaurus, vendor-prism в плагине it-async-chunks.

Docusaurus​

См. раздел Что такое Docusaurus выше.

Prism​

Библиотека подсветки синтаксиса в блоках кода; настраивается в themeConfig.prism.

Mermaid​

Язык диаграмм в markdown; тема @docusaurus/theme-mermaid + markdown.mermaid: true.

async-чанк​

Чанк с chunks: 'async' — грузится по требованию (embed-компоненты, тяжёлые демо).

embed-компонент​

React-обёртка iframe — ExternalPlayEmbed, ExternalCodeEmbed. Выделены в отдельную webpack-группу itEmbed.

Папка src/components/​

Кастомные React-компоненты для MDX и темы; async-группа itDemoAsync режет их на части до ~200 KB.

Теги​

HTML/meta-теги и YAML tags в frontmatter статей (обязательность, уровень). Open Graph — отдельный набор meta-тегов.

Подсветка​

Раскраска синтаксиса в code fence — Prism + тема Infima.

Блоки кода​

Fenced blocks ```language в Markdown/MDX.

additionalLanguages​

Массив имён языков в themeConfig.prism.additionalLanguages — какие грамматики Prism подключить.

docSidebar​

Тип пункта navbar — открывает боковое дерево с sidebarId: 'docsSidebar'.

DocSearchBar​

Кастомная строка поиска (Ctrl+K) из src/components/DocSearch/; тип navbar custom-docSearch.

swizzle​

CLI-команда копирования компонентов темы в src/theme/ для переопределения. См. Компоненты.

SaaS​

Software as a Service — поиск Algolia в облаке по подписке. Заменён локальным индексом. См. облачные модели.

Импорт​

Подключение модуля — import (ESM), require (CJS) или динамический import() для lazy-import.

Rspack bundler​

Быстрый сборщик, альтернатива Webpack; включается future.faster и @docusaurus/faster.

dev faster​

Режим ускоренной dev-сборки через Rspack; на Windows по умолчанию выключен.

Лимит открытых файлов​

Ограничение ОС на число одновременно открытых дескрипторов; при превышении — ошибка EMFILE. См. Архитектура.

i18n​

Internationalization — механизм мультиязычности Docusaurus (locales, defaultLocale).

Локализация​

Адаптация сайта под язык и регион — переводы UI, форматы дат, отдельные route на локаль. Сейчас одна локаль ru.

Связь с другими главами​

Полезные статьи энциклопедии​

Последнее обновление
Содержание