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

В Rspress можно либо объявить nav и sidebar в файле конфигурации, либо автоматически сгенерировать их из файлов _nav.json и _meta.json. Мы рекомендуем второй вариант, поскольку он позволяет сохранить файл конфигурации компактным, поддерживает HMR и при этом делает всё доступным через themeConfig.

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

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

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

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

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

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

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

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

[
  {
    "type": "dir-section-header",
    "name": "guide",
    "label": "Guide"
  },
  {
    "type": "dir-section-header",
    "name": "api",
    "label": "API"
  }
]

#Подсказки типов по JSON-схеме

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

Например, в VS Code можно добавить следующую настройку в файл .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. Например:

[
  {
    "text": "Guide",
    "link": "/guide/introduction",
    "activeMatch": "^/guide/"
  }
]

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

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

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, он представляет файл. Строка — это имя файла:

["introduction"]

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

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

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

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-узлу боковой панели; это необязательный параметр и по умолчанию не используется

Например:

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

#dir

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

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-узлу боковой панели; он необязательный и используется по умолчанию

Например:

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

[{ "type": "dir", "name": "guide" }]

["getting-started"]

#dir-section-header Новинка

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

Тип:

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

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

#divider

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

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

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

#section-header

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

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

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

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

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

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

#custom-link

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

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 — отображаемое название в боковой панели. Например:

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

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

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

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

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

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

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

[
  "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 автоматически сгенерировать боковую панель. Это работает, если директория содержит только документы, без поддиректорий, и не требуется настраивать порядок документов. Например:

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

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

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

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

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

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

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

["introduction"]

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

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

# Введение

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

#Значки и метки боковой панели

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

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

[
  {
    "type": "file",
    "name": "introduction",
    "label": "Introduction",
    "icon": "/icon.png",
    "tag": "new"
  }
]

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

[
  {
    "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.