Боковая панель
Хорошо организованная боковая панель — ключ к хорошей документации, поскольку это один из основных способов навигации пользователей по вашему сайту. Starlight предоставляет полный набор опций для настройки макета и содержимого боковой панели.
Стандартная боковая панель
По умолчанию Starlight автоматически генерирует боковую панель на основе структуры файловой системы вашей документации, используя свойство title
каждого файла в качестве элемента боковой панели.
Например, при следующей структуре файлов:
Директорияsrc/
Директорияcontent/
Директорияdocs/
Директорияconstellations/
- andromeda.md
- orion.md
Директорияstars/
- betelgeuse.md
Будет автоматически сгенерирована следующая боковая панель:
Узнайте больше об автоматически генерируемых боковых панелях в разделе Автогенерируемые группы.
Добавление ссылок и групп ссылок
Чтобы настроить свои ссылки и группы ссылок (внутри сворачиваемого заголовка) в боковой панели, используйте свойство starlight.sidebar
в astro.config.mjs
.
Комбинируя ссылки и группы, вы можете создавать разнообразные макеты боковой панели.
Ссылки
Добавьте ссылку на внутреннюю или внешнюю страницу, используя объект со свойствами label
и link
.
Конфигурация выше создаёт следующую боковую панель:
Группы
Вы можете структурировать вашу боковую панель, группируя связанные ссылки вместе под раскрывающимся заголовком. Группы могут содержать как ссылки, так и другие подгруппы.
Добавьте группу, используя объект со свойствами label
и items
.
label
будет использован как заголовок для группы.
Добавляйте ссылки или подгруппы в массив items
.
Вышеуказанная конфигурация генерирует следующую боковую панель:
Автогенерируемые группы
Starlight может автоматически генерировать группу в вашей боковой панели, основываясь на директориях в вашей документации. Это полезно, когда вы не хотите вручную вводить каждый элемент боковой панели в группе.
По умолчанию страницы сортируются в алфавитном порядке в соответствии со свойством slug
или именем файла.
Добавьте автогенерируемую группу, используя объект со свойствами label
и autogenerate
. Ваша конфигурация autogenerate
должна указывать directory
, которая будет использоваться для записей боковой панели. Например, со следующей конфигурацией:
И следующей структурой файлов:
Директорияsrc/
Директорияcontent/
Директорияdocs/
Директорияconstellations/
- carina.md
- centaurus.md
Директорияseasonal/
- andromeda.md
Будет сгенерирована следующая боковая панель:
Настройка сгенерированных ссылок через метаданные
Используйте поле sidebar
в метаданных страниц для настройки автоматически генерируемых ссылок.
Параметры в метаданных для боковой панели позволяют установить метку или добавить значок к ссылке, скрыть ссылку из боковой панели или определить её порядок в общем списке.
Автоматически созданная группа, включающая страницу с вышеуказанными метаданными, сгенерирует следующую боковую панель:
Значки
Ссылки также могут включать свойство badge
для отображения значка рядом с текстом ссылки.
Конфигурация выше создаст следующую боковую панель:
Варианты значков
Настройте стиль значка, используя объект со свойствами text
и variant
.
text
представляет содержимое для отображения (например, «Новое»).
Переопределите стиль default
, который использует акцентный цвет вашего сайта, установив свойство variant
в одно из следующих значений: note
, tip
, danger
, caution
или success
.
Конфигурация выше создаст следующую боковую панель:
Пользовательские HTML-атрибуты
Ссылки также могут включать свойство attrs
для добавления пользовательских HTML-атрибутов к элементу ссылки.
В следующем примере attrs
используется для добавления атрибута target="_blank"
, чтобы ссылка открывалась в новой вкладке, а также для применения атрибута style
, чтобы курсивом выделить метку ссылки:
Конфигурация выше создаст следующую боковую панель:
Интернационализация
Используйте свойство translations
для записей ссылок и групп, чтобы перевести метку ссылки или группы для каждого поддерживаемого языка, указав тег языка BCP-47, например, "en"
, "ru"
или "zh-CN"
в качестве ключа, и перевод метки — в качестве значения.
Свойство label
будет использоваться для локали по умолчанию и для языков без перевода.
При просмотре документации на бразильском португальском языке будет сгенерирована следующая боковая панель:
Сворачиваемые группы
Группы ссылок могут быть свёрнуты по умолчанию, если установить свойство collapsed
в true
.
Конфигурация выше создает следующую боковую панель:
Автогенерируемые группы учитывают значение collapsed
родительской группы:
Конфигурация выше создает следующую боковую панель:
Это поведение может быть переопределено путём установки свойства autogenerate.collapsed
.
Конфигурация выше создает следующую боковую панель: