跳转到内容
Starlight

侧边栏导航

一个组织良好的侧边栏是良好文档的关键，因为它是用户浏览你的站点的主要方式之一。Starlight 提供了一整套选项来自定义侧边栏布局和内容。

默认侧边栏

默认情况查下，Starlight 会根据你的文档文件系统结构自动生成侧边栏，使用每个文件的 title 属性作为侧边栏条目。

例如，给定以下文件结构：

  • 文件夹src/
    • 文件夹content/
      • 文件夹docs/
        • 文件夹constellations/
          • andromeda.md
          • orion.md
        • 文件夹stars/
          • betelgeuse.md

将会自动生成以下侧边栏：

在 自动生成的分组 章节了解更多关于自动生成侧边栏的内容。

添加链接和链接分组

要配置侧边栏链接和链接分组（在可折叠的标题中），请在 astro.config.mjs 中使用 starlight.sidebar 属性。

结合使用链接和链接分组，你可以创建各种侧边栏布局。

内部链接

使用带有 slug 属性的对象为 src/content/docs/ 中的页面添加链接。 默认情况下，链接页面的标题会被作为标签。

例如，进行以下的配置：

starlight({
  sidebar: [
    { slug: 'constellations/andromeda' },
    { slug: 'constellations/orion' },
  ],
});

并给定以下的文件结构：

  • 文件夹src/
    • 文件夹content/
      • 文件夹docs/
        • 文件夹constellations/
          • andromeda.md
          • orion.md

那么将会生成如下的侧边栏：

而要想覆盖从链接页面的 frontmatter 所推断出来的值，你可以添加 label，translations，以及 attrs 属性。

想了解更多通过 frontmatter 控制侧边栏外观的内容，请参阅 “在 frontmatter 中自定义自动生成的链接”。

内部链接的简易写法

内部链接也可以通过只提供一个页面标题字符串来指定。

例如，以下的配置等同于上面使用 slug 的配置：

starlight({
  sidebar: ['constellations/andromeda', 'constellations/orion'],
});

其他链接

使用带有 label 和 link 属性的对象，添加指向外部或非文档页面的链接。

starlight({
  sidebar: [
    // 指向网站中非文档页面的链接。
    { label: '流星商店', link: '/shop/' },
    // 指向 NASA 网站的外部链接。
    { label: 'NASA', link: 'https://www.nasa.gov/' },
  ],
});

上面的配置生成以下侧边栏：

分组

你可以通过在可折叠的标题下将相关链接组合在一起来为侧边栏添加结构。 分组可以包含链接和其他子组。

使用具有 label 和 items 属性的对象添加一个分组。 label 将用作分组的标题。 将链接或子组添加到 items 数组中。

starlight({
  sidebar: [
    // 一个名为 "星座" 的链接分组
    {
      label: '星座',
      items: [
        'constellations/carina',
        'constellations/centaurus',
        // 星座周期的嵌套链接分组。
        {
          label: '周期',
          items: [
            'constellations/andromeda',
            'constellations/orion',
            'constellations/ursa-minor',
          ],
        },
      ],
    },
  ],
});

上面的配置生成以下侧边栏：

自动生成的分组

Starlight 可以根据文档目录在侧边栏中自动生成一个分组。当你不想手动输入分组中的每个侧边栏项目时，这很有用。

默认情况下，页面按照文件 slug 的字母顺序排序。

使用具有 label 和 autogenerate 属性的对象添加自动生成的分组。autogenerate 的配置必须指定用于侧边栏条目的 directory 。例如，使用以下配置：

starlight({
  sidebar: [
    {
      label: '星座',
      // 自动生成一个链接分组，用于 '星座' 目录。
      autogenerate: { directory: 'constellations' },
    },
  ],
});

给定以下文件结构：

  • 文件夹src/
    • 文件夹content/
      • 文件夹docs/
        • 文件夹constellations/
          • carina.md
          • centaurus.md
          • 文件夹seasonal/
            • andromeda.md

将会自动生成以下侧边栏：

在 frontmatter 中自定义自动生成的链接

在单个页面中使用 sidebar frontmatter 字段 来自定义自动生成的链接。

侧边栏 frontmatter 选项允许你设置 自定义标签 或者为链接添加 徽章，隐藏 侧边栏中的链接，或者定义 自定义排序权重。

src/content/docs/example.md
---
title: 我的页面
sidebar:
  # 为链接设置自定义标签
  label: 自定义侧边栏 label
  # 为链接设置自定义顺序（数字越小显示在上方）
  order: 2
  # 为链接添加徽章
  badge:
    text: New
    variant: tip
---

一个包含上面 frontmatter 的页面的自动生成分组将会生成以下侧边栏：

徽章

链接、分组、自动生成的分组都可以包含一个 badge 属性，以在它们的标签旁边显示徽章。

starlight({
  sidebar: [
    {
      label: '星星',
      items: [
        // 带有 "Supergiant" 徽章的链接。
        {
          slug: 'stars/persei',
          badge: 'Supergiant',
        },
      ],
    },
    // 带有 "Outdated" 徽章的自动生成分组。
    {
      label: '卫星',
      badge: 'Outdated',
      autogenerate: { directory: 'moons' },
    },
  ],
});

以上配置将生成以下侧边栏：

徽章种类和自定义样式

使用具有 text、variant 和 class 属性的对象自定义徽章样式。

text 属性表示要显示的内容（例如 “New”）。

默认情况下，徽章将使用你的网站的强调色。要使用内置的徽章样式，请将 variant 属性设置为以下值之一：note、tip、danger、caution 或 success。

你还可以通过设置 class 属性为一个 CSS 类名来创建自定义的徽章样式。

starlight({
  sidebar: [
    {
      label: '星星',
      items: [
        // 一个带有黄色 "Stub" 徽章的链接。
        {
          slug: 'stars/sirius',
          badge: { text: 'Stub', 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"、"ar" 或 "zh-CN" 作为键，翻译后的标签作为值。

label 属性将用于默认语言和没有翻译的语言。

starlight({
  sidebar: [
    {
      label: '星座',
      translations: {
        'pt-BR': 'Constelações',
      },
      items: [
        {
          label: '仙女座',
          translations: {
            'pt-BR': 'Andrômeda',
          },
          slug: 'constellations/andromeda',
        },
        {
          label: '天蝎座',
          translations: {
            'pt-BR': 'Escorpião',
          },
          slug: 'constellations/scorpius',
        },
      ],
    },
  ],
});

浏览巴西葡萄牙语文档将生成以下侧边栏：

通过内部链接实现国际化

默认情况下，内部链接将从 frontmatter 自动使用翻译页面的标题：

starlight({
  sidebar: [
    {
      label: '星座',
      translations: {
        'pt-BR': 'Constelações',
      },
      items: [
        { slug: 'constellations/andromeda' },
        { slug: 'constellations/scorpius' },
      ],
    },
  ],
});

浏览巴西葡萄牙语文档将生成以下侧边栏：

在多语言网站中，slug 的值不会包含 URL 的语言部分。 例如，如果页面位于 en/intro 和 pt-br/intro，则在配置侧边栏时，slug 为 intro。

折叠分组

链接分组可以通过将 collapsed 属性设置为 true 来默认折叠。

starlight({
  sidebar: [
    {
      label: '星座',
      // 默认折叠分组
      collapsed: true,
      items: ['constellations/andromeda', 'constellations/orion'],
    },
  ],
});

以上配置将生成以下侧边栏：

自动生成的分组 遵循其父级分组的 collapsed 值：

starlight({
  sidebar: [
    {
      label: '星座',
      // 默认折叠分组及其自动生成的子组。
      collapsed: true,
      autogenerate: { directory: 'constellations' },
    },
  ],
});

以上配置将生成以下侧边栏：

这个行为可以通过定义 autogenerate.collapsed 属性来覆盖。

starlight({
  sidebar: [
    {
      label: '星座',
      // 不折叠 "星座" 分组，但折叠其自动生成的子组。
      collapsed: false,
      autogenerate: { directory: 'Constellations', collapsed: true },
    },
  ],
});

以上配置将生成以下侧边栏：