Боковая панель

Хорошо организованная боковая панель — ключ к хорошей документации, поскольку это один из основных способов навигации пользователей по вашему сайту. Starlight предоставляет полный набор опций для настройки макета и содержимого боковой панели.

Стандартная боковая панель

По умолчанию Starlight автоматически генерирует боковую панель на основе структуры файловой системы вашей документации, используя свойство title каждого файла в качестве элемента боковой панели.

Например, при следующей структуре файлов:

Директорияsrc/
- Директорияcontent/
  - Директорияdocs/
    Директорияguides/
    components.md
    i18n.md
    Директорияreference/
    configuration.md

Будет автоматически сгенерирована следующая боковая панель:

guides
- Компоненты
- Интернационализация (i18n)
reference
- Справочник по конфигурации

Узнайте больше об автоматически генерируемых боковых панелях в разделе Автогенерируемые группы.

Добавление ссылок и групп ссылок

Чтобы настроить свои ссылки и группы ссылок (внутри сворачиваемого заголовка) в боковой панели, используйте свойство starlight.sidebar в astro.config.mjs.

Комбинируя ссылки и группы, вы можете создавать разнообразные макеты боковой панели.

Ссылки

Добавьте ссылку на внутреннюю или внешнюю страницу, используя объект со свойствами label и link.

starlight({
  sidebar: [
    // Ссылка на руководство по CSS и стилизации.
    { label: 'CSS и стилизация', link: '/ru/guides/css-and-tailwind/' },
    // Внешняя ссылка на веб-сайт Astro.
    { label: 'Astro', link: 'https://astro.build/' },
  ],
});

Конфигурация выше создаёт следующую боковую панель:

Группы

Вы можете структурировать вашу боковую панель, группируя связанные ссылки вместе под раскрывающимся заголовком. Группы могут содержать как ссылки, так и другие подгруппы.

Добавьте группу, используя объект со свойствами label и items. label будет использован как заголовок для группы. Добавляйте ссылки или подгруппы в массив items.

starlight({
  sidebar: [
    // Группа ссылок с названием "Руководства".
    {
      label: 'Руководства',
      items: [
        { label: 'Компоненты', link: '/ru/guides/components/' },
        { label: 'Интернационализация (i18n)', link: '/ru/guides/i18n/' },
        // Вложенная группа ссылок.
        {
          label: 'Стилизация',
          items: [
            { label: 'CSS', link: '/ru/guides/css-and-tailwind/' },
            { label: 'Tailwind', link: '/ru/guides/css-and-tailwind/' },
            { label: 'Shiki', link: '/ru/guides/css-and-tailwind/' },
          ],
        },
      ],
    },
  ],
});

Вышеуказанная конфигурация генерирует следующую боковую панель:

Руководства
- Компоненты
- Интернационализация (i18n)
- Стилизация

Автогенерируемые группы

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

По умолчанию страницы сортируются в алфавитном порядке в соответствии со свойством slug или именем файла.

Добавьте автогенерируемую группу, используя объект со свойствами label и autogenerate. Ваша конфигурация autogenerate должна указывать directory, которая будет использоваться для записей боковой панели. Например, со следующей конфигурацией:

starlight({
  sidebar: [
    {
      label: 'Руководства',
      // Автоматически генерировать группу ссылок для директории "guides".
      autogenerate: { directory: 'guides' },
    },
  ],
});

И следующей структурой файлов:

Директорияsrc/
- Директорияcontent/
  - Директорияdocs/
    Директорияguides/
    components.md
    i18n.md
    Директорияadvanced/
    project-structure.md

Будет сгенерирована следующая боковая панель:

Руководства

Настройка сгенерированных ссылок через метаданные

Используйте поле sidebar в метаданных страниц для настройки автоматически генерируемых ссылок.

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

---
title: Моя страница
sidebar:
  # Установить текст для ссылки
  label: Текст в боковой панели
  # Установить порядок для ссылки (меньшие числа отображаются выше)
  order: 2
  # Добавить значок к ссылке
  badge:
    text: Новое
    variant: tip
---

Автоматически созданная группа, включающая страницу с вышеуказанными метаданными, сгенерирует следующую боковую панель:

Руководства

Значки

Ссылки также могут включать свойство badge для отображения значка рядом с текстом ссылки.

starlight({
  sidebar: [
    {
      label: 'Руководства',
      items: [
        // Ссылка со значком "Новое".
        {
          label: 'Компоненты',
          link: '/ru/guides/components/',
          badge: 'Новое',
        },
      ],
    },
    // Автогенерируемая группа со значком "Устарело".
    {
      label: 'Справочник',
      badge: 'Устарело',
      autogenerate: { directory: 'reference' },
    },
  ],
});

Конфигурация выше создаст следующую боковую панель:

Руководства
- Компоненты Новое
Справочник Устарело

Варианты значков

Настройте стиль значка, используя объект со свойствами text и variant.

text представляет содержимое для отображения (например, «Новое»). Переопределите стиль default, который использует акцентный цвет вашего сайта, установив свойство variant в одно из следующих значений: note, tip, danger, caution или success.

starlight({
  sidebar: [
    {
      label: 'Руководства',
      items: [
        // Ссылка с жёлтым значком "Экспериментально".
        {
          label: 'Компоненты',
          link: '/ru/guides/components/',
          badge: { text: 'Экспериментально', variant: 'caution' },
        },
      ],
    },
  ],
});

Конфигурация выше создаст следующую боковую панель:

Руководства
- Компоненты Экспериментально

Пользовательские HTML-атрибуты

Ссылки также могут включать свойство attrs для добавления пользовательских HTML-атрибутов к элементу ссылки.

В следующем примере attrs используется для добавления атрибута target="_blank", чтобы ссылка открывалась в новой вкладке, а также для применения атрибута style, чтобы курсивом выделить метку ссылки:

starlight({
  sidebar: [
    {
      label: 'Руководства',
      items: [
        // Внешняя ссылка на документацию Astro, открывающаяся в новой вкладке.
        {
          label: 'Документация Astro',
          link: 'https://docs.astro.build/ru/',
          attrs: { target: '_blank', style: 'font-style: italic' },
        },
      ],
    },
  ],
});

Конфигурация выше создаст следующую боковую панель:

Руководства
- Документация Astro

Интернационализация

Используйте свойство translations для записей ссылок и групп, чтобы перевести метку ссылки или группы для каждого поддерживаемого языка, указав тег языка BCP-47, например, "en", "ru" или "zh-CN" в качестве ключа, и перевод метки — в качестве значения. Свойство label будет использоваться для локали по умолчанию и для языков без перевода.

starlight({
  sidebar: [
    {
      label: 'Руководства',
      translations: {
        'pt-BR': 'Guias',
      },
      items: [
        {
          label: 'Компоненты',
          translations: {
            'pt-BR': 'Componentes',
          },
          link: '/guides/components/',
        },
        {
          label: 'Интернационализация (i18n)',
          translations: {
            'pt-BR': 'Internacionalização (i18n)',
          },
          link: '/guides/i18n/',
        },
      ],
    },
  ],
});

При просмотре документации на бразильском португальском языке будет сгенерирована следующая боковая панель:

Guías
- Componentes
- Internacionalización (i18n)

Сворачиваемые группы

Группы ссылок могут быть свёрнуты по умолчанию, если установить свойство collapsed в true.

starlight({
  sidebar: [
    {
      label: 'Руководства',
      // Сворачиваем группу по умолчанию.
      collapsed: true,
      items: [
        { label: 'Компоненты', link: '/ru/guides/components/' },
        { label: 'Интернационализация (i18n)', link: '/ru/guides/i18n/' },
      ],
    },
  ],
});

Конфигурация выше создает следующую боковую панель:

Руководства
- Компоненты
- Интернационализация (i18n)

Автогенерируемые группы учитывают значение collapsed родительской группы:

starlight({
  sidebar: [
    {
      label: 'Руководства',
      // Сворачиваем группу и её автогенерируемые подгруппы по умолчанию.
      collapsed: true,
      autogenerate: { directory: 'guides' },
    },
  ],
});

Конфигурация выше создает следующую боковую панель:

Руководства
- Компоненты
- Интернационализация (i18n)
- дополнительно
  - Структура проекта

Это поведение может быть переопределено путём установки свойства autogenerate.collapsed.

starlight({
  sidebar: [
    {
      label: 'Руководства',
      // Не сворачивать группу "Руководства", но свернуть её
      // автоматически сгенерированные подгруппы.
      collapsed: false,
      autogenerate: { directory: 'guides', collapsed: true },
    },
  ],
});

Конфигурация выше создает следующую боковую панель:

Руководства
- Компоненты
- Интернационализация (i18n)
- дополнительно
  - Структура проекта