Страницы

Starlight генерирует HTML-страницы вашего сайта на основе вашего контента с гибкими опциями, предоставляемыми через интерфейс Markdown. Кроме того, проекты Starlight имеют полный доступ к мощным инструментам создания страниц Astro. В этом руководстве объясняется, как работает генерация страниц в Starlight.

Содержимое страниц

Форматы файлов

Starlight поддерживает создание контента в Markdown и MDX без необходимости настройки. Вы можете добавить поддержку Markdoc, установив экспериментальную интеграцию Astro 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 на пользовательских страницах, оберните содержимое страницы компонентом <StarlightPage />. Это может быть полезно, если вы динамически генерируете контент, но всё же хотите использовать дизайн Starlight.

src/pages/custom-page/example.astro

---
import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
import CustomComponent from './CustomComponent.astro';
---

<StarlightPage frontmatter={{ title: 'Моя персонализированная страница' }}>
  <p>Это пользовательская страница с пользовательским компонентом:</p>
  <CustomComponent />
</StarlightPage>

Параметры

Компонент <StarlightPage /> принимает следующие параметры.

frontmatter (обязательно)

тип: StarlightPageFrontmatter

Установка метаданных для этой страницы, аналогично метаданным на страницах Markdown. Свойство title является обязательным, а все остальные свойства — нет.

Следующие свойства отличаются от метаданных Markdown:

• Свойство slug не поддерживается и устанавливается автоматически на основе URL-адреса пользовательской страницы.
• Свойство editUrl требует указания URL-адреса для отображения ссылки на редактирование.
• Свойство sidebar для настройки отображения страницы в автогенерируемых группах ссылок недоступно. Страницы, использующие компонент <StarlightPage />, не являются частью коллекции и не могут быть добавлены в автоматически созданную группу боковой панели.
• Свойство draft лишь отображает уведомление о том, что страница является черновиком, но не исключает её автоматически из производственных сборок.

sidebar

тип: SidebarEntry[]
по умолчанию: боковая панель, созданная на основе глобальной конфигурации sidebar

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

Например, следующая страница заменяет боковую панель по умолчанию ссылкой на домашнюю страницу и группой ссылок на различные созвездия. Текущая страница на боковой панели устанавливается с помощью свойства isCurrent, а к элементу ссылки добавлен дополнительный значок (badge).

<StarlightPage
  frontmatter={{ title: 'Орион' }}
  sidebar={[
    { label: 'Главная', href: '/' },
    {
      label: 'Созвездия',
      items: [
        { label: 'Андромеда', href: '/andromeda/' },
        { label: 'Орион', href: '/orion/', isCurrent: true },
        { label: 'Малая Медведица', href: '/ursa-minor/', badge: 'Заглушка' },
      ],
    },
  ]}
>
  Пример контента.
</StarlightPage>

hasSidebar

тип: boolean
по умолчанию: false если frontmatter.template имеет значение 'splash', в противном случае true

Отображение боковой панели на этой странице.

headings

тип: { depth: number; slug: string; text: string }[]
по умолчанию: []

Предоставление массива всех заголовков на этой странице. Starlight сгенерирует оглавление страницы из этих заголовков, если они предусмотрены.

dir

тип: 'ltr' | 'rtl'
по умолчанию: направление письма для текущей локали

Установка направления письма для содержимого этой страницы.

lang

тип: string
по умолчанию: язык текущей локали

Установка языкового тега BCP-47 для содержимого этой страницы, например: en, zh-CN или pt-BR.

isFallback

тип: boolean
по умолчанию: false

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