sidebars.js

Что такое sidebars.js

sidebars.js — конфигурационный файл Docusaurus в корне репозитория. Он описывает левое боковое меню (sidebar) для плагина документации — какие статьи и категории показывать, в каком порядке и куда ведёт клик по заголовку группы.

Без sidebars.js тысячи файлов в docs/ остались бы доступны только по прямому URL, без пункта в навигации. Файл связывают с navbar через sidebarPath: './sidebars.js' в docusaurus.config.js и sidebarId: 'docsSidebar'.

Документация в Docusaurus — это всё содержимое docs/ (markdown, MDX, метаданные). Боковое меню — визуальное дерево слева на странице статьи; оно строится из sidebars.js плюс правил autogenerated.

Структура файла

// sidebars.js
const sidebars = {
  docsSidebar: [
    // массив категорий и документов
  ],
};

export default sidebars;

Элемент	Роль
`const sidebars`	Объект с одним или несколькими именованными sidebar
`docsSidebar`	id sidebar — на него ссылается navbar
`[...]`	Массив корневых пунктов меню
`export default`	ESM-экспорт — Docusaurus 3 читает `.js` с `export default` так же, как ESM-скрипты в `scripts/`

export и export default

В JavaScript-модулях export выставляет имена наружу, export default — главное значение модуля. При import sidebars from './sidebars.js' подтягивается объект { docsSidebar: [...] }. Один default на файл — типичный стиль конфигов Node и Docusaurus.

В themeConfig пункт "Энциклопедия" имеет тип docSidebar.

{
  type: 'docSidebar',
  sidebarId: 'docsSidebar',
  position: 'left',
  label: 'Энциклопедия',
}

При открытии doc-layout Docusaurus подставляет дерево docsSidebar. Опция routeBasePath: '/' в пресете classic превращает id документа в URL от корня (/about/project, /encyclopedia/intro).

Страница, которой нет ни в ручном items, ни в папке autogenerated, всё равно собирается (если лежит в docs/), но остаётся только по прямой ссылке или из поиска.

Верхний уровень меню

Сейчас в docsSidebar восемь корневых блоков — семь категорий и один одиночный документ.

Категория	`dirName` / якорь	Как заданы `items`
О проекте	`about/*`	Ручная категория + вложенная autogenerated
Энциклопедия	`encyclopedia`	autogenerated
Инструменты	`tools`	autogenerated
Глоссарий	`glossary`	autogenerated
Лаборатория	`lab`	autogenerated
Контекст	`context`	autogenerated
Философия	`philosophy`	autogenerated
Общее содержание	`toc`	один `type: 'doc'`

Корневой массив — это упорядоченный список. Порядок объектов в sidebars.js задаёт порядок разделов в sidebar сверху вниз.

Каждый пункт меню — объект с полем type или короткая строка-id документа.

`type`	Назначение	Ключевые поля
`category`	Раскрывающаяся категория	`label`, `link`, `items`
`doc`	Один документ без группы	`id`, `label`
`autogenerated`	Дерево из папки `docs/`	`dirName`
строка `'about/project'`	Сокращение для `type: 'doc'`	путь-id относительно `docs/`

label

Текст в боковом меню. Для autogenerated подпись категории чаще берётся из _category_.json или title / sidebar_label в frontmatter.

link

Опциональная ссылка при клике на заголовок категории (стрелка раскрытия работает отдельно).

link: { type: 'doc', id: 'about/project' }

`link.type`	Поведение
`doc`	Открывает указанный документ по id
`generated-index`	Автоматическая страница-оглавление раздела (см. category.json)

Без link заголовок категории только раскрывает список дочерних пунктов.

items

Массив дочерних элементов — строки-id, вложенные category, блоки autogenerated. Это дерево категорий в JSON-подобной структуре на JavaScript.

Ручная категория "О проекте"

Раздел about собран вручную — порядок страниц "О проекте" не полностью доверен файловой системе.

{
  type: 'category',
  label: 'О проекте',
  link: { type: 'doc', id: 'about/project' },
  items: [
    'about/project',
    'about/collections',
    'about/collections/pervye-shagi',
    'about/interactive',
    'about/author',
    'about/license',
    'about/manifest',
    {
      type: 'category',
      label: 'Как устроена Вселенная IT',
      link: { type: 'doc', id: 'about/kak-ustroena-vselennaya-it/index' },
      items: [
        { type: 'autogenerated', dirName: 'about/kak-ustroena-vselennaya-it' },
      ],
    },
  ],
},

Решение	Зачем
Явный список `items`	Фиксированный порядок статей about вне алфавита папки
`link` на `about/project`	Клик по "О проекте" открывает индекс раздела
Вложенная autogenerated	Подраздел "Как устроена Вселенная IT" растёт по файлам в папке без правки каждой главы вручную

Остальные корневые разделы (энциклопедия, lab, tools…) используют только { type: 'autogenerated', dirName: '...' } — автоматический подбор всего дерева папки.

autogenerated — дерево из файловой системы

{
  type: 'autogenerated',
  dirName: 'encyclopedia',
}

Docusaurus сканирует docs/encyclopedia/ и строит дерево категорий по папкам и файлам. Автоматический подбор не дублирует тысячи строк в sidebars.js — структура энциклопедии живёт в каталогах и метаданных.

Источники порядка и подписей (по приоритету Docusaurus).

position в _category_.json папки — позиция категории среди соседей.
sidebar_position в frontmatter файла — порядок статей внутри папки.
Лексикографический порядок имён файлов и папок — если sidebar_position / position не заданы.

Алфавитный порядок файлов в папке

Если у двух соседних .md нет sidebar_position, они сортируются как строки по алфавиту (locale-aware сравнение), в том порядке, в каком имена лежат в каталоге ОС. Поэтому в "Как устроена Вселенная IT" главы названы 01-arkhitektura.md, 02-docusaurus-config.md… — префиксы 01-, 02- держат логическую последовательность при лексикографии.

В энциклопедии папки и файлы именуют латиницей (5-01-javascript, 1-basics) — стабильный порядок на Windows и Linux и предсказуемые slug.

JSON-метаданные папок — category.json

В каждой папке docs/ может лежать _category_.json — JSON-файл с метаданными для autogenerated. Sidebar и Docusaurus читают его при сборке дерева.

Пример корня энциклопедии.

{
  "label": "Энциклопедия",
  "link": {
    "type": "generated-index",
    "title": "Энциклопедия"
  }
}

Пример вложенного раздела "Как устроена Вселенная IT".

{
  "label": "Как устроена Вселенная IT",
  "position": 8,
  "link": {
    "type": "doc",
    "id": "about/kak-ustroena-vselennaya-it/index"
  }
}

Поле	Смысл
`label`	Подпись категории в sidebar
`position`	Позиция среди соседних папок (меньше — выше)
`link`	Куда ведёт клик по заголовку категории
`collapsed`	Свернута ли группа по умолчанию (если задано)

generated-index создаёт страницу-оглавление со списком дочерних документов — как у "Лаборатория" и корня "Энциклопедия". link.type: 'doc' открывает конкретный index-файл.

index, intro и страницы "о разделе"

Файл	Типичная роль	Пример в проекте
`index.md` / `index.mdx`	Индекс подпапки, вход в раздел	`about/kak-ustroena-vselennaya-it/index.mdx`
`intro.md`	Вводная "о разделе", часто с `DocCardList`	`encyclopedia/intro.md`, `lab/intro.md`
`project.md`	Главная страница раздела about	`about/project.md`

index — оглавление или обзор папки; в id попадает как .../index. intro — соглашение имени для вводных статей верхнего уровня раздела; в sidebars.js на них вешают link корневых категорий (encyclopedia/intro, lab/intro).

Для "Как устроена Вселенная IT" index.mdx задаёт sidebar_position: 0 и slug /about/kak-ustroena-vselennaya-it, чтобы оглавление раздела шло первым в autogenerated-дереве.

slug, путь, имя файла и id документа

Три понятия часто путают — у каждого своя роль.

Понятие	Что это	Пример
Путь	Расположение файла в `docs/`	`docs/about/kak-ustroena-vselennaya-it/04-sidebars.md`
Имя файла	Последний сегмент пути с расширением	`04-sidebars.md`
id документа	Путь без `docs/` и без расширения — ключ в sidebar и `link.id`	`about/kak-ustroena-vselennaya-it/04-sidebars`
slug	Часть URL в браузере; задаётся в frontmatter	`/about/kak-ustroena-vselennaya-it/sidebars`

---
title: sidebars.js
sidebar_position: 4
slug: /about/kak-ustroena-vselennaya-it/sidebars
---

slug переопределяет URL, id остаётся привязанным к файлу. В sidebar и в link: { type: 'doc', id: '...' } всегда используют id, в адресной строке — slug (если указан).

В docusaurus.config.js numberPrefixParser: false — числовые префиксы вроде 01- в имени файла не вырезаются автоматически из id; для красивого URL префикс убирают через явный slug (01-arkhitektura.md → /about/.../arkhitektura).

Файл	id	slug (URL)
`docs/about/project.md`	`about/project`	по умолчанию `/about/project`
`docs/encyclopedia/intro.md`	`encyclopedia/intro`	`/encyclopedia/intro`
`docs/about/kak-ustroena-vselennaya-it/01-arkhitektura.md`	`about/kak-ustroena-vselennaya-it/01-arkhitektura`	`/about/kak-ustroena-vselennaya-it/arkhitektura`

sidebar_position и sidebar_label

В frontmatter статьи.

sidebar_position: 4
sidebar_label: "Короткая подпись в меню"

Поле	Эффект
`sidebar_position`	Числовая позиция среди соседей в одной папке; меньше — выше
`sidebar_label`	Текст пункта в sidebar вместо `title`
`title`	Заголовок страницы и запасная подпись в меню, если `sidebar_label` нет

Пример энциклопедии — encyclopedia/intro.md с sidebar_label: "Энциклопедия — о разделе" при title той же формулировки.

Изменить подпись без переименования файла — править sidebar_label или label в _category_.json.

Одиночный документ без категории

{
  type: 'doc',
  id: 'toc',
  label: 'Общее содержание',
}

id: 'toc' → файл docs/toc.md. Такой пункт стоит в корне массива docsSidebar рядом с категориями, без раскрывающейся группы.

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

Добавить статью в "О проекте"

Положить файл в docs/about/ и добавить строку в items или положить в папку с autogenerated (как главы "Как устроена Вселенная IT").

'about/my-new-page',

Новый корневой раздел

{
  type: 'category',
  label: 'Новый раздел',
  link: { type: 'doc', id: 'new-section/intro' },
  items: [{ type: 'autogenerated', dirName: 'new-section' }],
},

Создать docs/new-section/intro.md и при необходимости docs/new-section/_category_.json.

Исключить из items и из autogenerated-папки — редкий приём; чаще используют черновик или отдельный маршрут в src/pages/.

Поменять порядок в autogenerated-папке

Задать sidebar_position в frontmatter или переименовать файлы с учётом лексикографии (01-, 02-…).

Ограничения autogenerated

Глубокие деревья (энциклопедия ~3000 статей) тяжёлые для dev — sidebar пересобирается при старте.
Смешение кириллицы и латиницы в именах папок даёт разный порядок на разных ОС — в проекте пути латиницей.
Дубликаты id недопустимы — один файл, один id.
Документ вне sidebar всё ещё в сборке и в поиске, но без пункта в меню.

Глоссарий

sidebars.js

Файл конфигурации левого меню документации Docusaurus; экспортирует объект sidebar (в проекте — docsSidebar).

Сайдбар

Sidebar — боковая панель навигации по разделу docs. В коде темы — компонент DocSidebar (Структура src/).

Документация

В контексте Docusaurus — контент плагина @docusaurus/plugin-content-docs, каталог docs/, sidebar, версии. См. docs в конфиге.

Боковое меню

Русскоязычное название sidebar — вертикальный список категорий и статей слева от текста статьи.

Верхняя панель сайта — секция themeConfig.navbar в docusaurus.config.js. Пункт docSidebar привязывает layout к sidebarId: 'docsSidebar'.

Категория

Группа пунктов меню с type: 'category' — раскрывающийся узел дерева. В файловой системе — обычно подпапка docs/.../.

Статья

Один документ .md / .mdx в docs/; в sidebar — лист дерева или строка-id в items.

autogenerated

Режим { type: 'autogenerated', dirName: '...' } — Docusaurus сам строит поддерево из папки по _category_.json, frontmatter и именам файлов.

Автоматический подбор

Синоним логики autogenerated — содержимое папки становится пунктами меню без ручного перечисления каждого файла.

export

Ключевое слово ES-модуля для именованного экспорта (export const x).

export default

Главный экспорт модуля; в sidebars.js — объект sidebars.

about

Раздел docs/about/ — "О проекте"; в sidebar задан ручной списком с вложенным техническим подразделом.

Ручная категория

Категория, чьи items перечислены явно в sidebars.js (в дополнение к autogenerated).

index

Файл index.md / index.mdx — входная страница папки; id папка/index.

intro

Соглашение имени вводной статьи раздела (intro.md); часто цель link корневой категории в sidebar.

Список

Упорядоченная последовательность элементов; в sidebar — items категории или корневой массив docsSidebar.

Массив

Структура данных JSON/JavaScript [a, b, c]; корень docsSidebar и поле items — массивы. См. раздел про массивы в статье JSON.

items

Поле категории — дочерние узлы sidebar (строки, category, autogenerated).

label

Отображаемый текст пункта или заголовка категории в меню.

type

Дискриминатор вида узла sidebar — category, doc, autogenerated.

link

Объект { type, id? / title? } — куда ведёт клик по заголовку категории.

Дерево категорий

Иерархия папок docs/ и узлов sidebar — корень, ветви, листья-документы.

Лексикография

Лексикографический порядок — сортировка строк по алфавиту (как в словаре). Docusaurus использует его для имён файлов без sidebar_position.

Позиция

Число position / sidebar_position — место элемента в списке (меньше — выше).

id документа

Уникальный ключ документа — путь от docs/ без расширения; используется в sidebar, link.id, внутренних ссылках Docusaurus.

slug

Путь URL страницы; переопределяется в frontmatter, не меняя id. Подробнее в docusaurus.config.

Путь

Полный маршрут к файлу в репозитории или сегменты URL; в sidebar id совпадает с логическим путём внутри docs/.

Имя файла

Последний компонент пути (04-sidebars.md); влияет на id и на лексикографический порядок.

category.json

JSON-метаданные папки для autogenerated — label, position, link, collapsed.

sidebar_label

Поле frontmatter — подпись пункта в sidebar без смены title страницы.

Страница

Собранный HTML/MDX-документ с URL; пункт sidebar ведёт на страницу по slug.

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

docusaurus.config.js — sidebarPath, routeBasePath, numberPrefixParser, navbar docSidebar.
Архитектура — навигация между сервисами и разделами сайта.
Структура src/ — swizzle DocSidebar, resize, fallback.
package.json и стек — npm start, сборка, frontmatter в пайплайне поиска.

Что такое sidebars.js​

Структура файла​

export и export default​

Связь с navbar и маршрутами​

Верхний уровень меню​

Поля узла sidebar​

label​

link​

items​

Ручная категория "О проекте"​

autogenerated — дерево из файловой системы​

Алфавитный порядок файлов в папке​

JSON-метаданные папок — category.json​

index, intro и страницы "о разделе"​

slug, путь, имя файла и id документа​

sidebar_position и sidebar_label​

Одиночный документ без категории​

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

Добавить статью в "О проекте"​

Новый корневой раздел​

Скрыть файл из sidebar, но оставить URL​

Поменять порядок в autogenerated-папке​

Ограничения autogenerated​

Глоссарий​

sidebars.js​

Сайдбар​

Документация​

Боковое меню​

navbar​

Категория​

Статья​

autogenerated​

Автоматический подбор​

export​

export default​

about​

Ручная категория​

index​

intro​

Список​

Массив​

items​

label​

type​

link​

Дерево категорий​

Лексикография​

Позиция​

id документа​

slug​

Путь​

Имя файла​

category.json​

sidebar_label​

Страница​

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

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

См. также

📄️Как устроена Вселенная IT

📄️Архитектура

📄️docusaurus.config.js

📄️package.json и стек

📄️TypeScript

📄️Структура src/

📄️Темы и стили

📄️Данные и скрипты

📄️Компоненты

Что такое sidebars.js

Структура файла

export и export default

Связь с navbar и маршрутами

Верхний уровень меню

Поля узла sidebar

label

link

items

Ручная категория "О проекте"

autogenerated — дерево из файловой системы

Алфавитный порядок файлов в папке

JSON-метаданные папок — category.json

index, intro и страницы "о разделе"

slug, путь, имя файла и id документа

sidebar_position и sidebar_label

Одиночный документ без категории

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

Добавить статью в "О проекте"

Новый корневой раздел

Скрыть файл из sidebar, но оставить URL

Поменять порядок в autogenerated-папке

Ограничения autogenerated

Глоссарий

sidebars.js

Сайдбар

Документация

Боковое меню

navbar

Категория

Статья

autogenerated

Автоматический подбор

export

export default

about

Ручная категория

index

intro

Список

Массив

items

label

type

link

Дерево категорий

Лексикография

Позиция

id документа

slug

Путь

Имя файла

category.json

sidebar_label

Страница

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

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