> For AI agents: the complete documentation index is available at /rspress-russian/llms.txt, the full documentation bundle is available at /rspress-russian/llms-full.txt.

# Автонавигация

В Rspress можно либо объявить [nav](/rspress-russian/api/config/config-theme.md#nav) и [sidebar](/rspress-russian/api/config/config-theme.md#sidebar) в файле конфигурации, либо автоматически сгенерировать их из файлов `_nav.json` и `_meta.json`. Мы рекомендуем второй вариант, поскольку он позволяет сохранить файл конфигурации компактным, поддерживает HMR и при этом делает всё доступным через `themeConfig`.

:::tip
Автоматическая генерация навигационной и боковой панелей работает только в том случае, если в `rspress.config.ts` не определены `nav` или `sidebar`.
:::

## Базовое использование

Rspress генерирует навигационную панель из `_nav.json`, а боковую панель — из `_meta.json`. Файл `_nav.json`, определяющий навигационную панель, располагается в корне директории документации, а файлы `_meta.json`, определяющие боковую панель, — в её подкаталогах. Например:

```tree
docs
├── _nav.json // навигация
└── guide
    ├── _meta.json // сайдбар
    ├── introduction.mdx
    └── advanced
        ├── _meta.json // сайдбар
        └── plugin-development.md
```

Если ваш сайт использует i18n, разместите файл `_nav.json`, определяющий навигационную панель, в каталоге каждой локали:

```tree
docs
├── en
│   ├── _nav.json // навигация
│   └── guide
│       ├── _meta.json // сайдбар
│       ├── introduction.mdx
│       ├── install.mdx
│       └── advanced
│           ├── _meta.json // сайдбар
│           └── plugin-development.md
└── ru
    ├── _nav.json // навигация
    └── guide
        ├── _meta.json // сайдбар
        ├── introduction.mdx
        ├── install.mdx
        └── advanced
            ├── _meta.json // сайдбар
            └── plugin-development.md
```

## Использование глобальной боковой панели

По умолчанию (когда в корне существует только `_nav.json`) Rspress генерирует **отдельную боковую панель для каждого подкаталога**. Боковая панель переключается автоматически в зависимости от активного элемента навигации. Например, при нажатии на элемент навигации «Руководство» отображается боковая панель руководства, а при нажатии на «API» — боковая панель API:

```tree
docs
├── _nav.json
├── guide
│   ├── _meta.json  // боковая панель для /guide
│   └── ...
└── api
    ├── _meta.json  // боковая панель для /api
    └── ...
```

Если вы хотите, чтобы все страницы **использовали единую глобальную боковую панель** вместо переключения по навигации, вы можете добавить файл `_meta.json` на корневом уровне директории docs (рядом с `_nav.json`).

Этот подход лучше работает для сайтов документации с **меньшим количеством пунктов навигации и более простой структурой**. Поскольку боковая панель остаётся одинаковой независимо от того, какой пункт навигации активен, это хорошее решение, когда вы хотите организовать весь сайт под одной единой боковой панелью:

```tree
docs
├── _nav.json
├── _meta.json  // корневой _meta.json → глобальная боковая панель
├── guide
│   ├── _meta.json
│   └── ...
└── api
    ├── _meta.json
    └── ...
```

Когда в корне проекта существует файл `_meta.json`, Rspress будет генерировать единую боковую панель (с ключом `'/'`) для всех страниц, независимо от того, какой пункт навигации активен. Корневой `_meta.json` служит точкой входа для всего дерева боковой панели, и вы обычно можете организовывать поддиректории с помощью заголовков разделов:

```json title="docs/_meta.json"
[
  {
    "type": "dir-section-header",
    "name": "guide",
    "label": "Guide"
  },
  {
    "type": "dir-section-header",
    "name": "api",
    "label": "API"
  }
]
```

## Подсказки типов по JSON-схеме \{#json-schema-type-hint}

Для улучшения редактирования `_nav.json` и `_meta.json` Rspress предоставляет две схемы для подсказок в IDE: `@rspress/core/meta-json-schema.json` и `@rspress/core/nav-json-schema.json`.

Например, в VS Code можно добавить следующую настройку в файл `.vscode/settings.json`:

```json title=".vscode/settings.json"
{
  //...
  "json.schemas": [
    {
      "fileMatch": ["**/_meta.json"],
      "url": "./node_modules/@rspress/core/meta-json-schema.json"
      // или "url": "https://unpkg.com/@rspress/core@2.0.0/meta-json-schema.json"
    },
    {
      "fileMatch": ["**/_nav.json"],
      "url": "./node_modules/@rspress/core/nav-json-schema.json"
      // или "url": "https://unpkg.com/@rspress/core@2.0.0/nav-json-schema.json"
    }
  ]
  // ...
}
```

## Настройка навигации

В файле `_nav.json` указывается массив элементов. Его структура и тип полностью совпадают с конфигурацией `nav` стандартной темы. Подробности — в разделе [конфигурация `nav`](/rspress-russian/api/config/config-theme.md#nav). Например:

```json title="docs/_nav.json"
[
  {
    "text": "Guide",
    "link": "/guide/introduction",
    "activeMatch": "^/guide/"
  },
  {
    "text": "API",
    "items": [
      {
        "text": "Configuration",
        "link": "/api/config/config-basic"
      },
      {
        "text": "CLI",
        "link": "/api/commands"
      }
    ]
  },
  {
    "text": "Changelog",
    "link": "https://github.com/web-infra-dev/rspress/releases"
  }
]
```

## Настройка сайдбара

В файле `_meta.json` указывается массив элементов, каждый из которых имеет следующий тип:

```ts
export type FileSideMeta = {
  type: 'file';
  name: string;
  label?: string;
  icon?: string;
  tag?: string;
  overviewHeaders?: number[];
  context?: string;
};

export type DirSideMeta = {
  type: 'dir';
  name: string;
  label?: string;
  collapsible?: boolean;
  collapsed?: boolean;
  icon?: string;
  tag?: string;
  overviewHeaders?: number[];
  context?: string;
};

export type DirSectionHeaderSideMeta = Omit<DirSideMeta, 'type'> &
  Omit<SectionHeaderMeta, 'type'> & { type: 'dir-section-header' };

export type DividerSideMeta = {
  type: 'divider';
  dashed?: boolean;
};

export type SectionHeaderMeta = {
  type: 'section-header';
  label: string;
  icon?: string;
  tag?: string;
};

export type CustomLinkMeta =
  | {
      // ссылка на файл
      type: 'custom-link';
      label: string;
      icon?: string;
      tag?: string;
      overviewHeaders?: number[];
      context?: string;
      link: string;
    }
  | {
      // ссылка на директорию
      type: 'custom-link';
      label: string;
      icon?: string;
      tag?: string;
      overviewHeaders?: number[];
      context?: string;
      link?: string;
      collapsible?: boolean;
      collapsed?: boolean;
      items: _CustomLinkMetaWithoutTypeField[];
    };

export type SideMetaItem =
  | FileSideMeta
  | DirSideMeta
  | DirSectionHeaderSideMeta
  | DividerSideMeta
  | SectionHeaderMeta
  | CustomLinkMeta
  | string;
```

### file

- Если элемент является `string`, он представляет файл. Строка — это имя файла:

```json
["introduction"]
```

Имя файла может содержать расширение или быть без него. Например, `introduction` будет распознано как `introduction.mdx`.

- Если элемент является объектом, он может описывать файл, директорию или пользовательскую ссылку.

Чтобы описать **файл**, используйте следующий тип:

```ts
export type FileSideMeta = {
  type: 'file';
  name: string;
  label?: string;
  icon?: string;
  tag?: string;
  overviewHeaders?: number[];
  context?: string;
};
```

- `name` — имя файла с расширением или без него
- `label` — отображаемое название файла в боковой панели. Если `label` не указано, Rspress автоматически использует заголовок H1 документа
- `overviewHeaders` — управляет тем, какие заголовки отображаются на обзорной странице файла; это необязательный параметр, по умолчанию `[2]`
- `context` — добавляет атрибут `data-context` к сгенерированному DOM-узлу боковой панели; это необязательный параметр и по умолчанию не используется

Например:

```json
{
  "type": "file",
  "name": "introduction",
  "label": "Введение"
}
```

### dir

Чтобы описать **директорию**, используйте следующий тип:

```ts
export type DirSideMeta = {
  type: 'dir';
  name: string;
  label?: string;
  collapsible?: boolean;
  collapsed?: boolean;
  icon?: string;
  tag?: string;
  overviewHeaders?: number[];
  context?: string;
};
```

- `name` — имя директории
- `label` — отображаемое название директории в боковой панели
- `collapsible` — управляет возможностью сворачивания директории
- `collapsed` — задаёт, свернута ли она по умолчанию
  — `overviewHeaders` — управляет тем, какие заголовки отображаются на обзорных страницах файлов внутри этой директории; это необязательный параметр, по умолчанию `[2]`
  — `context` — добавляет атрибут `data-context` к сгенерированному DOM-узлу боковой панели; он необязательный и используется по умолчанию

Например:

```json
{
  "type": "dir",
  "name": "advanced",
  "label": "Дополнительно",
  "collapsible": true,
  "collapsed": false
}
```

:::tip

Чтобы отображать документ при клике на директорию в боковой панели, создайте файл `index.mdx` внутри этой директории. Например:

```tree
docs
└── basic
    ├── guide
    │   ├── index.mdx
    │   ├── getting-started.mdx
    │   └── _meta.json
    └── _meta.json
```

```json title="basic/_meta.json"
[{ "type": "dir", "name": "guide" }]
```

```json title="basic/guide/_meta.json"
["getting-started"]
```

Эта боковая панель содержит только документ `getting-started`. Когда пользователь кликает на директорию `Guide`, Rspress отображает содержимое `index.mdx`.

:::

### dir-section-header Новинка
При описании **директории** также можно использовать `dir-section-header`. Он ведёт себя как `"type": "dir"`, но отображается в интерфейсе иначе. Его часто используют на первом уровне, где заголовок директории отображается как [заголовок раздела](#section-header) на одном уровне с файлами внутри директории.

Тип:

```ts
export type DirSectionHeaderSideMeta = Omit<DirSideMeta, 'type'> &
  Omit<SectionHeaderMeta, 'type'> & { type: 'dir-section-header' };
```

```json
{
  "type": "dir-section-header",
  "name": "advanced",
  "label": "Дополнительно",
  "collapsible": true,
  "collapsed": false
}
```

### divider

Чтобы описать **разделитель**, используйте следующий тип:

```ts
export type DividerSideMeta = {
  type: 'divider';
  dashed?: boolean;
};
```

Если `dashed` установлено в `true`, линия разделителя будет пунктирной, иначе — сплошной.

### section-header

Чтобы описать **заголовок раздела**, используйте следующий тип:

```ts
export type SectionHeaderMeta = {
  type: 'section-header';
  label: string;
  icon?: string;
  tag?: string;
};
```

Здесь `label` — отображаемое название заголовка раздела в боковой панели. Например:

```json
{
  "type": "section-header",
  "label": "Заголовок раздела"
}
```

Заголовки секций упрощают группировку документов и директорий в боковой панели. Их можно комбинировать с `divider`, чтобы более явно разделять группы:

```json
[
  {
    "type": "section-header",
    "label": "Раздел 1"
  },
  "introduction",
  {
    "type": "divider"
  },
  {
    "type": "section-header",
    "label": "Раздел 2"
  },
  "advanced"
]
```

### custom-link

Чтобы описать **пользовательскую ссылку**, используйте следующий тип:

```ts
export type CustomLinkMeta =
  | {
      // ссылка на файл
      type: 'custom-link';
      label: string;
      icon?: string;
      tag?: string;
      overviewHeaders?: number[];
      context?: string;
      link: string;
    }
  | {
      // ссылка на директорию
      type: 'custom-link';
      label: string;
      icon?: string;
      tag?: string;
      overviewHeaders?: number[];
      context?: string;
      link?: string;
      collapsible?: boolean;
      collapsed?: boolean;
      items: _CustomLinkMetaWithoutTypeField[];
    };
```

Здесь `link` — целевая ссылка, а `label` — отображаемое название в боковой панели. Например:

```json
{
  "type": "custom-link",
  "link": "/my-link",
  "label": "Моя ссылка"
}
```

Поле `link` поддерживает внешние ссылки, например:

```json
{
  "type": "custom-link",
  "link": "https://github.com",
  "label": "GitHub"
}
```

Также можно использовать поле `items`, чтобы создать вложенные произвольные ссылки, например:

```json
{
  "type": "custom-link",
  "label": "Моя ссылка",
  "items": [
    {
      "type": "custom-link",
      "label": "Вложенная ссылка 1",
      "link": "/sub-link-1"
    },
    {
      "type": "custom-link",
      "label": "Вложенная ссылка 2",
      "link": "/sub-link-2"
    }
  ]
}
```

### Полный пример

Вот полный пример с использованием трёх перечисленных выше типов ссылок:

```json
[
  "install",
  {
    "type": "file",
    "name": "introduction",
    "label": "Введение"
  },
  {
    "type": "dir",
    "name": "advanced",
    "label": "Дополнительно",
    "collapsible": true,
    "collapsed": false
  },
  {
    "type": "custom-link",
    "link": "/my-link",
    "label": "Моя ссылка"
  }
]
```

### Использование без конфигурации

В некоторых директориях можно не использовать `_meta.json` и позволить Rspress автоматически сгенерировать боковую панель. Это работает, если директория содержит только документы, без поддиректорий, и не требуется настраивать порядок документов. Например:

```tree
docs
├── _meta.json
└── guide
  ├── _meta.json
  └── basic
    ├── introduction.mdx
    ├── install.mdx
    └── plugin-development.md
```

В директории `guide` настройте `_meta.json` следующим образом:

```json
[
  {
    "type": "dir",
    "name": "basic",
    "label": "Основы",
    "collapsible": true,
    "collapsed": false
  }
]
```

В директории `basic` можно не использовать `_meta.json`; в этом случае Rspress автоматически создаст боковую панель и отсортирует файлы по алфавиту. Чтобы настроить порядок, добавьте числовые префиксы к именам файлов:

```tree
basic
  ├── 1-introduction.mdx
  ├── 2-install.mdx
  └── 3-plugin-development.md
```

## Настройка элементов файлов с помощью метаданных

Большинство параметров отображения автоматически сгенерированных элементов файлов можно задать в блоке метаданных страницы: `title`, `icon`, `tag`, `overviewHeaders` и `context`.

Структурные параметры следует хранить в `_meta.json`, включая порядок элементов, `type`, `name`, группы каталогов, заголовки секций, пользовательские ссылки, `collapsible` и `collapsed`. Для метаданных, относящихся к конкретной странице, рекомендуется использовать метаданные, чтобы содержимое и его представление в боковой панели находились в одном месте.

Например, `_meta.json` может определять, какие файлы отображаются и в каком порядке:

```json title="docs/guide/_meta.json"
["introduction"]
```

Затем настройте параметры отображения элемента файла в метаданных страницы:

```md title="docs/guide/introduction.mdx"
---
title: Введение
icon: /icon.png
tag: new
overviewHeaders: [2, 3]
context: guide-introduction
---

# Введение
```

Если для одного и того же элемента файла одно и то же поле задано в обоих местах, для полей `icon`, `tag`, `overviewHeaders` и `context` приоритет имеет frontmatter, а для заголовка страницы приоритет имеет `label` из `_meta.json`. Для группы каталогов приоритет имеет `_meta.json` по сравнению с метаданными из её индексной страницы.

## Значки и метки боковой панели \{#sidebar-icons-and-tags}

Используйте `icon`, чтобы добавить значок перед заголовком в боковой панели. Рекомендуемый и наиболее распространённый способ — поместить изображение в каталог `public` и указать его через абсолютный путь.

Например, поместите локальное изображение в `docs/public/icon.png`, а затем укажите его в `_meta.json`:

```json title="docs/_meta.json"
[
  {
    "type": "file",
    "name": "introduction",
    "label": "Introduction",
    "icon": "/icon.png",
    "tag": "new"
  }
]
```

Вы также можете указать встроенную строку SVG, если хотите встроить значок непосредственно в конфигурацию:

```json title="docs/_meta.json"
[
  {
    "type": "file",
    "name": "introduction",
    "icon": "<svg width=\"1em\" height=\"1em\" viewBox=\"0 0 32 32\"><path fill=\"currentColor\" d=\"M4 6h24v2H4zm0 18h24v2H4zm0-12h24v2H4zm0 6h24v2H4z\"/></svg>"
  }
]
```

Также поддерживаются эмодзи, внешние URL-адреса и data URL. Существующая настройка `tag` по-прежнему отображается после заголовка.

Подробную информацию о `tag` см. в разделе [Компонент Tag](/rspress-russian/ui/layout-components/tag.md).
