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

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

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

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

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

Директорияsrc/
- Директорияcontent/
  - Директорияdocs/
    Директорияconstellations/
    andromeda.md
    orion.md
    Директорияstars/
    betelgeuse.md

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

constellations
- Андромеда
- Орион
stars
- Бетельгейзе

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

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

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

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

Внутренние ссылки

Добавьте ссылку на страницу в src/content/docs/, используя объект со свойством slug. Заголовок связанной страницы будет использоваться в качестве метки по умолчанию.

Например, со следующей конфигурацией:

starlight({
  sidebar: [
    { slug: 'constellations/andromeda' },
    { slug: 'constellations/orion' },
  ],
});

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

Директорияsrc/
- Директорияcontent/
  - Директорияdocs/
    Директорияconstellations/
    andromeda.md
    orion.md

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

Андромеда
Орион

Чтобы переопределить значения, полученные из метаданных связанной страницы, вы можете добавить свойства label, translations и attrs.

См. Настройка сгенерированных ссылок для получения более подробной информации об управлении внешним видом боковой панели из метаданных страницы.

Сокращенное обозначение внутренних ссылок

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

Например, следующая конфигурация эквивалентна конфигурации выше, в которой используется slug:

starlight({
  sidebar: ['constellations/andromeda', 'constellations/orion'],
});

Другие ссылки

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

starlight({
  sidebar: [
    // Ссылка на страницу, не связанную с документацией, на этом сайте.
    { label: 'Meteor Store', link: '/shop/' },
    // Внешняя ссылка на веб-сайт NASA.
    { label: 'NASA', link: 'https://www.nasa.gov/' },
  ],
});

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

Meteor Store
NASA

Группы

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

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

starlight({
  sidebar: [
    // Группа ссылок с названием «Созвездия».
    {
      label: 'Созвездия',
      items: [
        'constellations/carina',
        'constellations/centaurus',
        // Вложенная группа ссылок для сезонных созвездий.
        {
          label: 'Сезонные',
          items: [
            'constellations/andromeda',
            'constellations/orion',
            'constellations/ursa-minor',
          ],
        },
      ],
    },
  ],
});

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

Созвездия
- Карина
- Центавр
- Сезонные

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

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

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

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

starlight({
  sidebar: [
    {
      label: 'Созвездия',
      // Автогенерация группы ссылок для директории 'constellations'.
      autogenerate: { directory: 'constellations' },
    },
  ],
});

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

Директорияsrc/
- Директорияcontent/
  - Директорияdocs/
    Директорияconstellations/
    carina.md
    centaurus.md
    Директорияseasonal/
    andromeda.md

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

Созвездия
- Карина
- Центавр
- seasonal
  - Андромеда

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

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

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

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

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

Руководства

Значки

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

starlight({
  sidebar: [
    {
      label: 'Звёзды',
      items: [
        // Ссылка со значком «Сверхгигант».
        {
          slug: 'stars/persei',
          badge: 'Сверхгигант',
        },
      ],
    },
    // Автогенерируемая группа со значком "Устарело".
    {
      label: 'Луны',
      badge: 'Устарело',
      autogenerate: { directory: 'moons' },
    },
  ],
});

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

Звёзды
- Персей Сверхгигант
Луны Устарело

Варианты значков и индивидуальная стилизация

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

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

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

starlight({
  sidebar: [
    {
      label: 'Звёзды',
      items: [
        // Ссылка с жёлтым значком «Заглушка»
        {
          slug: 'stars/sirius',
          badge: { text: 'Заглушка', variant: 'caution' },
        },
      ],
    },
  ],
});

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

Звёзды
- Сириус Заглушка

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

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

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

starlight({
  sidebar: [
    {
      label: 'Ресурсы',
      items: [
        // Внешняя ссылка на сайт NASA, открывающаяся в новой вкладке.
        {
          label: 'NASA',
          link: 'https://www.nasa.gov/',
          attrs: { target: '_blank', style: 'font-style: italic' },
        },
      ],
    },
  ],
});

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

Ресурсы
- NASA

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

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

starlight({
  sidebar: [
    {
      label: 'Созвездия',
      translations: {
        'pt-BR': 'Constelações',
      },
      items: [
        {
          label: 'Андромеда',
          translations: {
            'pt-BR': 'Andrômeda',
          },
          slug: 'constellations/andromeda',
        },
        {
          label: 'Скорпион',
          translations: {
            'pt-BR': 'Escorpião',
          },
          slug: 'constellations/scorpius',
        },
      ],
    },
  ],
});

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

Constelação
- Andrômeda
- Escorpião

Интернационализация с внутренними ссылками

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

starlight({
  sidebar: [
    {
      label: 'Созвездия',
      translations: {
        'pt-BR': 'Constelações',
      },
      items: [
        { slug: 'constellations/andromeda' },
        { slug: 'constellations/scorpius' },
      ],
    },
  ],
});

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

Constelações
- Andrômeda
- Escorpião

На многоязычных сайтах значение slug не включает языковую часть URL. Например, если у вас есть страницы en/intro и pt-br/intro, при настройке боковой панели в качестве slug будет intro.

Интернационализация с помощью значков

Для значков свойство text может быть строкой, а для многоязычных сайтов — объектом со значениями для каждой локали. При использовании объектной формы ключи должны быть тегами BCP-47 (например: en, ar или zh-CN):

starlight({
  sidebar: [
    {
      label: 'Созвездия',
      translations: {
        'pt-BR': 'Constelações',
      },
      items: [
        {
          slug: 'constellations/andromeda',
          badge: {
            text: {
              ru: 'Новинка',
              'pt-BR': 'Novo',
            },
          },
        },
      ],
    },
  ],
});

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

Constelações
- Andrômeda Novo

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

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

starlight({
  sidebar: [
    {
      label: 'Созвездия',
      // Сворачивание группы по умолчанию
      collapsed: true,
      items: [
        items: ['constellations/andromeda', 'constellations/orion'],
      ],
    },
  ],
});

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

Созвездия
- Андромеда
- Орион

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

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

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

Созвездия
- Карина
- Центавр
- seasonal
  - Андромеда

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

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

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

Созвездия
- Карина
- Центавр
- seasonal
  - Андромеда