Страницы
Starlight генерирует HTML-страницы вашего сайта на основе вашего контента с гибкими опциями, предоставляемыми через интерфейс Markdown. Кроме того, проекты Starlight имеют полный доступ к мощным инструментам создания страниц Astro. В этом руководстве объясняется, как работает генерация страниц в Starlight.
Содержимое страниц
Заголовок раздела «Содержимое страниц»Форматы файлов
Заголовок раздела «Форматы файлов»Starlight поддерживает создание контента в Markdown и MDX без необходимости настройки. Вы можете добавить поддержку Markdoc, следуя руководству.
Добавление страниц
Заголовок раздела «Добавление страниц»Добавляйте новые страницы на свой сайт, создавая файлы .md
или .mdx
в src/content/docs/
.
Используйте подпапки для организации файлов и создания нескольких сегментов пути.
Например, следующая файловая структура будет генерировать страницы example.com/hello-world
и example.com/reference/faq
:
Директорияsrc/
Директорияcontent/
Директорияdocs/
- hello-world.md
Директорияreference/
- faq.md
Типобезопасные метаданные
Заголовок раздела «Типобезопасные метаданные»Все страницы Starlight используют настраиваемый общий набор свойств метаданных для контроля отображения страницы:
---title: Привет, мир!description: Это страница на моем сайте, работающем на Starlight---
Если вы что-то забудете, Starlight сообщит вам об этом.
Пользовательские страницы
Заголовок раздела «Пользовательские страницы»Для расширенных вариантов использования вы можете добавлять собственные страницы, создав каталог src/pages/
.
Каталог src/pages/
использует маршрутизацию на основе файлов Astro и включает поддержку файлов с расширением .astro
помимо других форматов страниц.
Это полезно, если вам нужно создать страницу с полностью настраиваемым макетом или создать страницу из альтернативного источника данных.
Например, в этом проекте содержимое Markdown смешивается в src/content/docs/
с маршрутами Astro и HTML в src/pages/
:
Директорияsrc/
Директорияcontent/
Директорияdocs/
- hello-world.md
Директорияpages/
- custom.astro
- archived.html
Подробнее читайте в руководстве «Страницы» в документации Astro.
Использование дизайна Starlight на пользовательских страницах
Заголовок раздела «Использование дизайна Starlight на пользовательских страницах»Чтобы использовать макет Starlight на пользовательских страницах, оберните содержимое страницы компонентом <StarlightPage />
.
Это может быть полезно, если вы динамически генерируете контент, но всё же хотите использовать дизайн Starlight.
---import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';import CustomComponent from './CustomComponent.astro';---
<StarlightPage frontmatter={{ title: 'Моя персонализированная страница' }}> <p>Это пользовательская страница с пользовательским компонентом:</p> <CustomComponent /></StarlightPage>
Параметры
Заголовок раздела «Параметры»Компонент <StarlightPage />
принимает следующие параметры.
frontmatter
(обязательно)
Заголовок раздела «frontmatter (обязательно)»тип: StarlightPageFrontmatter
Установка метаданных для этой страницы, аналогично метаданным на страницах Markdown.
Свойство title
является обязательным, а все остальные свойства — нет.
Следующие свойства отличаются от метаданных Markdown:
- Свойство
slug
не поддерживается и устанавливается автоматически на основе URL-адреса пользовательской страницы. - Свойство
editUrl
требует указания URL-адреса для отображения ссылки на редактирование. - Свойство
sidebar
для настройки отображения страницы в автогенерируемых группах ссылок недоступно. Страницы, использующие компонент<StarlightPage />
, не являются частью коллекции и не могут быть добавлены в автоматически созданную группу боковой панели. - Свойство
draft
лишь отображает уведомление о том, что страница является черновиком, но не исключает её автоматически из продакшен-сборок.
sidebar
Заголовок раздела «sidebar»тип: SidebarItem[]
по умолчанию: боковая панель, созданная на основе глобальной конфигурации sidebar
Предоставление настраиваемой боковой панели навигации для этой страницы. Если этот параметр не установлен, на странице будет использоваться глобальная боковая панель по умолчанию.
Например, следующая страница переопределяет стандартную боковую панель со ссылкой на главную страницу и группой ссылок на другие пользовательские страницы.
<StarlightPage frontmatter={{ title: 'Орион' }} sidebar={[ { label: 'Главная', link: '/' }, { label: 'Созвездия', items: [ { label: 'Андромеда', link: '/andromeda/' }, { label: 'Орион', link: '/orion/' }, { label: 'Малая Медведица', link: '/ursa-minor/', badge: 'Заглушка' }, ], }, ]}> Пример контента.</StarlightPage>
Подробнее о доступных вариантах настройки боковой панели см. в руководстве Боковая панель.
hasSidebar
Заголовок раздела «hasSidebar»тип: boolean
по умолчанию: false
если frontmatter.template
имеет значение 'splash'
, в противном случае true
Отображение боковой панели на этой странице.
headings
Заголовок раздела «headings»тип: { depth: number; slug: string; text: string }[]
по умолчанию: []
Предоставление массива всех заголовков на этой странице. Starlight сгенерирует оглавление страницы из этих заголовков, если они предусмотрены.
тип: 'ltr' | 'rtl'
по умолчанию: направление письма для текущей локали
Установка направления письма для содержимого этой страницы.
тип: string
по умолчанию: язык текущей локали
Установка языкового тега BCP-47 для содержимого этой страницы, например: en
, zh-CN
или pt-BR
.
isFallback
Заголовок раздела «isFallback»тип: boolean
по умолчанию: false
Отображение резервного контента, если перевод на текущий язык отсутствует.