Конфигурация
Настройка интеграции starlight
Starlight — это интеграция, построенная на основе веб-фреймворка Astro. Вы можете настроить свой проект в файле конфигурации astro.config.mjs
:
Вы можете передать следующие параметры интеграции starlight
.
title
(обязателен)
тип: string | Record<string, string>
Задайте название для вашего сайта. Будет использоваться в метаданных и в заголовке вкладки браузера.
Значение может быть строкой, а для многоязычных сайтов — объектом со значениями для каждой локали.
При использовании объектной формы ключи должны быть тегами BCP-47 (например, en
, ru
или zh-CN
):
description
тип: string
Задайте описание для вашего сайта. Используется в метаданных, передаваемых поисковым системам, в теге <meta name="description">
, если description
не задан в метаданных страницы.
logo
тип: LogoConfig
Установите изображение логотипа, которое будет отображаться в навигационной панели вместе с заголовком сайта или вместо него. Вы можете задать одно свойство src
или установить отдельные источники изображения для стилей light
и dark
.
LogoConfig
tableOfContents
тип: false | { minHeadingLevel?: number; maxHeadingLevel?: number; }
по умолчанию: { minHeadingLevel: 2; maxHeadingLevel: 3; }
Настройте оглавление, отображаемое справа на каждой странице. По умолчанию в оглавление будут включены заголовки <h2>
и <h3>
.
editLink
тип: { baseUrl: string }
Включите ссылки “Редактировать эту страницу”, задав базовый URL, который они должны использовать. Конечной ссылкой будет editLink.baseUrl
+ путь к текущей странице. Например, чтобы разрешить редактирование страниц в репозитории withastro/starlight
на GitHub:
При такой конфигурации страница /introduction
будет иметь ссылку редактирования, указывающую на https://github.com/withastro/starlight/edit/main/src/content/docs/introduction.md
.
sidebar
тип: SidebarItem[]
Настройте элементы навигации боковой панели вашего сайта.
Боковая панель — это массив ссылок и групп ссылок.
За исключением элементов, использующих slug
, каждый элемент должен иметь label
и одно из следующих свойств:
-
link
— одиночная ссылка на определённый URL, например,'/home'
или'https://example.com'
. -
slug
— ссылка на внутреннюю страницу, например,'guides/getting-started'
. -
items
— массив, содержащий дополнительные ссылки и подгруппы боковой панели. -
autogenerate
— объект, указывающий каталог ваших документов для автоматической генерации группы ссылок.
Внутренние ссылки также могут быть указаны в виде строки, а не объекта со свойством slug
.
Сортировка
Автогенерируемые группы боковых панелей сортируются по имени файла в алфавитном порядке.
Например, страница, созданная на основе astro.md
, будет отображаться выше страницы для starlight.md
.
Сворачиваемые группы
Группы ссылок раскрываются по умолчанию. Вы можете изменить это поведение, установив для свойства collapsed
группы значение true
.
Автогенерируемые подгруппы по умолчанию уважают свойство collapsed
своей родительской группы. Установите свойство autogenerate.collapsed
, чтобы переопределить его.
Перевод меток
Если ваш сайт многоязычный, считается, что label
каждого элемента соответствует локали по умолчанию. Вы можете установить свойство translations
, чтобы предоставить метки для других поддерживаемых вами языков:
SidebarItem
BadgeConfig
locales
тип: { [dir: string]: LocaleConfig }
Настройте интернационализацию (i18n) для вашего сайта, установив, какие locales
поддерживаются.
В каждой записи в качестве ключа должен использоваться каталог, в котором хранятся файлы этого языка.
LocaleConfig
Для каждой локали можно задать следующие параметры:
label
(required)
тип: string
Метка для этого языка, которую нужно показывать пользователям, например, в переключателе языков. Чаще всего вы хотите, чтобы это было название языка в том виде, в котором пользователь этого языка ожидал бы его прочитать, например "English"
, "Русский
или "简体中文"
.
lang
тип: string
Метка BCP-47 для этого языка, например, "en"
, "ru"
, или "zh-CN"
. Если не задано, то по умолчанию будет использоваться имя каталога языка. Языковые теги с региональными подтегами (например, "pt-BR"
или "en-US"
) будут использовать встроенные переводы пользовательского интерфейса для своего базового языка, если не будут найдены переводы для конкретного региона.
dir
тип: 'ltr' | 'rtl'
Направление письма на этом языке; "ltr"
— слева направо (по умолчанию) или "rtl"
— справа налево.
Корневая локаль
Вы можете использовать язык по умолчанию без каталога /lang/
, установив локаль root
:
Например, это позволит вам обслуживать /getting-started/
как маршрут по умолчанию и использовать /ru/getting-started/
как эквивалентную русскую страницу.
defaultLocale
тип: string
Установите язык, который используется по умолчанию для этого сайта.
Значение должно соответствовать одному из ключей вашего объекта locales
.
(Если языком по умолчанию является ваша корневая локаль, это можно пропустить).
Локаль по умолчанию будет использоваться для предоставления резервного содержимого, если перевод отсутствует.
social
тип: Partial<Record<'azureDevOps' | 'backstage' | 'bitbucket' | 'blueSky' | 'codeberg' | 'codePen' | 'discord' | 'discourse' | 'email' | 'facebook' | 'farcaster' | 'github' | 'gitlab' | 'gitter' | 'hackerOne' | 'instagram' | 'linkedin' | 'mastodon' | 'matrix' | 'microsoftTeams' | 'nostr' | 'openCollective' | 'patreon' | 'pinterest' | 'reddit' | 'rss' | 'signal' | 'slack' | 'stackOverflow' | 'telegram' | 'threads' | 'tiktok' | 'twitch' | 'twitter' | 'x.com' | 'youtube' | 'zulip', string>>
Дополнительные сведения об аккаунтах в социальных сетях для этого сайта. При добавлении любого из них они будут отображаться в виде ссылок-иконок в шапке сайта.
customCss
тип: string[]
Предоставьте CSS-файлы для настройки внешнего вида вашего сайта Starlight.
Поддерживаются локальные CSS-файлы относительно корня вашего проекта, например: './src/custom.css'
, и CSS, которые вы установили как модуль npm, например: '@fontsource/roboto'
.
expressiveCode
тип: StarlightExpressiveCodeOptions | boolean
по умолчанию: true
Starlight использует Expressive Code для визуализации блоков кода и добавляет поддержку выделения частей примеров кода, добавления имён файлов к блокам кода и многое другое. Смотрите руководство Блоки кода, чтобы узнать, как использовать синтаксис выразительного кода в Markdown и MDX-содержимом.
Вы также можете использовать любые стандартные параметры конфигурации Expressive Code, как некоторые свойства, специфичные для Starlight, установив их в опции expressiveCode
Starlight.
Например, установите опцию styleOverrides
в Expressive Code, чтобы переопределить CSS по умолчанию. Это позволяет настраивать код, например, сделать блокам кода закругленные углы:
Если вы хотите отключить Expressive Code, установите expressiveCode: false
в конфигурации Starlight:
В дополнение к стандартным параметрам Expressive Code вы также можете установить следующие свойства, специфичные для Starlight, в вашей конфигурации expressiveCode
для дальнейшей настройки поведения темы для ваших блоков кода:
themes
тип: Array<string | ThemeObject | ExpressiveCodeTheme>
по умолчанию: ['starlight-dark', 'starlight-light']
Установите темы, используемые для оформления блоков кода. См. документацию по темам Expressive Code для получения подробной информации о поддерживаемых форматах тем.
По умолчанию Starlight использует тёмный и светлый варианты темы Night Owl Сары Драснер.
Если вы предоставите хотя бы одну тёмную и одну светлую тему, Starlight автоматически синхронизирует активную тему блока кода с текущей темой сайта.
Настройте это поведение с помощью параметра useStarlightDarkModeSwitch
.
useStarlightDarkModeSwitch
тип: boolean
по умолчанию: true
Если установлено значение true, блоки кода автоматически переключаются между светлой и тёмной темами при изменении темы сайта. Если установлено значение false, вам придется вручную добавить CSS для переключения между несколькими темами.
useStarlightUiThemeColors
тип: boolean
по умолчанию: true
если themes
не задано, иначе — false
Если true
, то для цветов элементов пользовательского интерфейса кодового блока (фонов, кнопок, теней и т. д.) используются CSS-переменные Starlight, соответствующие цветовой теме сайта.
Если false
, то для этих элементов используются цвета, предоставляемые активной темой подсветки синтаксиса.
pagefind
тип: boolean
по умолчанию: true
Определите, включен ли в Starlight поставщик поиска по сайту по умолчанию — Pagefind.
Установите значение false
, чтобы отключить индексацию вашего сайта с помощью Pagefind.
Это также скроет стандартный пользовательский интерфейс поиска, если он используется.
Pagefind не может быть включен, если для параметра prerender
установлено значение false
.
prerender
тип: boolean
по умолчанию: true
Определите, должны ли страницы Starlight предварительно отрисовываться в статический HTML или отрисовываться по требованию с помощью SSR-адаптера.
Страницы Starlight предварительно отрисовываются по умолчанию.
Если вы используете адаптер SSR и хотите рендерить страницы Starlight по требованию, установите prerender: false
.
head
тип: HeadConfig[]
Добавьте пользовательские теги в <head>
вашего сайта Starlight.
Может пригодиться для добавления аналитики и других сторонних скриптов и ресурсов.
Записи в head
преобразуются непосредственно в HTML-элементы и не проходят через обработку скриптов или стилей Astro.
Если вам нужно импортировать локальные ресурсы, такие как скрипты, стили или изображения, переопределите компонент Head.
HeadConfig
lastUpdated
тип: boolean
по умолчанию: false
Укажите, показывать ли в нижнем колонтитуле дату последнего обновления страницы.
По умолчанию эта функция полагается на историю Git вашего репозитория и может быть неточной на некоторых платформах развёртывания, создающих копии репозитория, включающие только самый последний коммит. Страница может переопределить эту настройку или дату, основанную на Git, с помощью поля lastUpdated
frontmatter.
pagination
тип: boolean
по умолчанию: true
Определите, должен ли нижний колонтитул включать ссылки на предыдущую и следующую страницы.
Страница может переопределить эту настройку или текст ссылки и/или URL с помощью полей prev
и next
в метаданных страницы.
favicon
тип: string
по умолчанию: '/favicon.svg'
Задайте путь к фавиконке по умолчанию для вашего сайта, который должен находиться в директории public/
и быть валидным (.ico
, .gif
, .jpg
, .png
или .svg
) файлом иконок.
Если вам нужно задать дополнительные варианты или резервные фавиконки, вы можете добавить теги с помощью опции head
:
titleDelimiter
тип: string
по умолчанию: '|'
Устанавливает разделитель между заголовком страницы и заголовком сайта в теге <title>
, который отображается на вкладках браузера.
По умолчанию каждая страница имеет <title>
вида Заголовок страницы | Заголовок сайта
.
Например, эта страница называется «Конфигурация», а этот сайт — «Starlight», поэтому <title>
для этой страницы будет «Конфигурация | Starlight».
disable404Route
тип: boolean
по умолчанию: false
Отключает внедрение стандартной страницы 404 Starlight. Чтобы использовать в своем проекте собственный маршрут src/pages/404.astro
, установите для этого параметра значение true
.
components
тип: Record<string, string>
Укажите пути к компонентам для переопределения реализаций Starlight по умолчанию.
См. Справочник по переопределениям для получения подробной информации обо всех компонентах, которые можно переопределить.
plugins
тип: StarlightPlugin[]
Расширьте Starlight с помощью пользовательских плагинов. Плагины вносят изменения в ваш проект, чтобы изменить или добавить функции Starlight.
Посетите витрину плагинов, чтобы увидеть список доступных плагинов.
См. Справочник по плагинам для получения подробной информации о создании собственных плагинов.
credits
Включите отображение ссылки «Сделано с помощью Starlight» в подвале вашего сайта.