页面

Starlight 会根据你的内容生成站点的 HTML 页面，并通过 Markdown frontmatter 提供灵活的选项。此外，Starlight 项目可以完全访问 Astro 强大的页面生成工具。本指南将介绍 Starlight 中的页面生成工作原理。

内容页面

文件格式

Starlight 支持在 Markdown 和 MDX 中编写内容，无需任何配置。你可以按照 “Markdoc” 指南 添加对 Markdoc 的支持。

添加页面

通过在 src/content/docs/ 中创建 .md 或 .mdx 文件来为你的网站添加新页面。使用子文件夹来组织文件并创建多级路径。

例如，以下文件结构将生成 example.com/hello-world 和 example.com/reference/faq 两个页面。

• 目录src/

  • 目录content/

    • 目录docs/

      • hello-world.md
      • 目录reference/

        • faq.md

类型安全的 frontmatter

所有 Starlight 页面共享一套可自定义的通用 frontmatter 属性，以控制页面的显示方式。

---
title: Hello, World!
description: This is a page in my Starlight-powered site
---

如果你忘记了任何重要的东西，Starlight 会提醒你。

自定义页面

对于高级用例，你可以通过创建 src/pages/ 目录来添加自定义页面。`src/pages/` 目录使用 Astro 的基于文件的路由，并支持 .astro 文件及其他页面格式。如果你需要构建具有完全自定义布局的页面或从替代数据源生成页面，这将非常有用。

例如，这个项目将 src/content/docs/ 中的 Markdown 内容与 src/pages/ 中的 Astro 和 HTML 路由混合在一起。

• 目录src/

  • 目录content/

    • 目录docs/

      • hello-world.md
  • 目录pages/

    • custom.astro
    • archived.html

在 Astro 文档的“页面”指南中阅读更多内容。

在自定义页面中使用 Starlight 的设计

要在自定义页面中使用 Starlight 布局，请使用 <StarlightPage> 组件包装页面内容。如果你正在动态生成内容但仍想使用 Starlight 的设计，这将非常有用。此组件必须是文件中的第一个导入，以设置 级联层 并确保可预测的 CSS 顺序。

要为标题添加与 Starlight 的 Markdown 锚点链接样式相匹配的锚点链接，你可以在自定义页面中使用 <AnchorHeading> 组件。

src/pages/custom-page/example.astro

---
// Import the `<StarlightPage>` component first to set up cascade layers.
import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';

// Import any other components you want to use in your custom page.
import AnchorHeading from '@astrojs/starlight/components/AnchorHeading.astro';
import CustomComponent from './CustomComponent.astro';
---

<StarlightPage frontmatter={{ title: 'My custom page' }}>
  <p>This is a custom page with a custom component:</p>
  <CustomComponent />

  <AnchorHeading level="2" id="learn-more">Learn more</AnchorHeading>
  <p>
    <a href="https://starlight.astro.js.cn/">Read more in the Starlight docs</a>
  </p>
</StarlightPage>

<StarlightPage> 组件

<StarlightPage /> 组件使用 Starlight 的布局和样式渲染整个页面的内容。

---
// Import the `<StarlightPage>` component first to set up cascade layers.
import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
---

<StarlightPage frontmatter={{ title: 'My custom page' }}>
  <!-- Custom page content -->
</StarlightPage>

由于 Astro 中导入顺序的工作方式，<StarlightPage /> 组件必须是文件中的第一个导入，以设置 Starlight 内部用于管理其样式顺序的级联层。

<StarlightPage /> 组件接受以下 props。

frontmatter

必需
类型： StarlightPageFrontmatter

为该页面设置 frontmatter 属性，类似于 Markdown 页面中的 frontmatter。 title 属性是必需的，所有其他属性都是可选的。

以下属性与 Markdown frontmatter 不同：

• slug 属性不受支持，并会根据自定义页面的 URL 自动设置。
• editUrl 选项需要一个 URL 才能显示编辑链接。
• 用于自定义页面在自动生成的链接组中显示方式的 sidebar frontmatter 属性不可用。使用 <StarlightPage /> 组件的页面不属于集合，因此无法添加到自动生成的侧边栏组中。
• draft 选项仅显示一个页面为草稿的通知，但不会自动将其从生产构建中排除。

sidebar

类型： SidebarItem[]
默认值：根据全局 sidebar 配置生成的侧边栏

为此页面提供自定义的站点导航侧边栏。如果未设置，该页面将使用默认的全局侧边栏。

例如，以下页面使用指向主页的链接和一组指向其他各种自定义页面的链接覆盖了默认侧边栏。

<StarlightPage
  frontmatter={{ title: 'Orion' }}
  sidebar={[
    { label: 'Home', link: '/' },
    {
      label: 'Constellations',
      items: [
        { label: 'Andromeda', link: '/andromeda/' },
        { label: 'Orion', link: '/orion/' },
        { label: 'Ursa Minor', link: '/ursa-minor/', badge: 'Stub' },
      ],
    },
  ]}
>
  Example content.
</StarlightPage>

请参阅“侧边栏导航”指南，了解有关自定义侧边栏的可用选项的更多信息。

hasSidebar

类型： boolean
默认值：如果 frontmatter.template 是 'splash'，则为 false，否则为 true

控制是否在此页面上显示侧边栏。

headings

类型： { depth: number; slug: string; text: string }[]
默认值： []

提供此页面上所有标题的数组。如果提供了这些标题，Starlight 将根据它们生成页面的目录。

dir

类型： 'ltr' | 'rtl'
默认值：当前区域设置的书写方向

设置此页面内容的书写方向。

lang

类型： string
默认值：当前区域设置的语言

为此页面的内容设置 BCP-47 语言标签，例如 en、 zh-CN 或 pt-BR。

isFallback

类型： boolean
默认值： false

指示此页面是否因当前语言没有翻译而使用回退内容。

<AnchorHeading> 组件

<AnchorHeading /> 组件会渲染一个带有可点击锚点链接的 HTML 标题元素，其样式与 Starlight 的 Markdown 样式相匹配。

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

<AnchorHeading level="2" id="sub-heading">Sub heading</AnchorHeading>

它接受以下 props 以及任何其他有效的全局 HTML 属性。

level

必需
类型： 1 | 2 | 3 | 4 | 5 | 6

要渲染的标题级别。例如，level="1" 将渲染一个 <h1> 元素。

id

必需
类型： string

此标题的唯一 ID。这将用作渲染后标题的 id 属性，并且锚点图标将链接到它。