title	description
Боковая панель	Узнайте, как установить и настроить навигационные ссылки в боковой панели сайта Starlight.

import { FileTree } from '@astrojs/starlight/components'; import SidebarPreview from '~/components/sidebar-preview.astro';

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

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

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

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

src/
- content/
  - docs/
    - constellations/
      - andromeda.md
      - orion.md
    - stars/
      - betelgeuse.md

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

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

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

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

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

Ссылки

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

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

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

Группы

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

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

starlight({
	sidebar: [
		// Группа ссылок с названием «Созвездия».
		{
			label: 'Созвездия',
			items: [
				{ label: 'Карина', link: '/constellations/carina/' },
				{ label: 'Центавр', link: '/constellations/centaurus/' },
				// Вложенная группа ссылок для сезонных созвездий.
				{
					label: 'Сезонные',
					items: [
						{ label: 'Андромеда', link: '/constellations/andromeda/' },
						{ label: 'Орион', link: '/constellations/orion/' },
						{ label: 'Малая Медведица', link: '/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

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

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

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

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

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

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

:::note Конфигурация sidebar в метаданных используется только для автоматически генерируемых ссылок и будет проигнорирована для вручную определённых ссылок. :::

Значки

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

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

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

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

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

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

starlight({
	sidebar: [
		{
			label: 'Звёзды',
			items: [
				// Ссылка с жёлтым значком «Заглушка»
				{
					label: 'Сириус',
					link: '/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' },
				},
			],
		},
	],
});

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

sidebar.mdx

sidebar.mdx

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

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

Ссылки

Группы

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

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

Значки

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

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

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

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

Files

sidebar.mdx

Latest commit

History

sidebar.mdx

File metadata and controls

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

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

Ссылки

Группы

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

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

Значки

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

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

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

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