跳转到内容
Starlight

侧边栏导航

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

默认侧边栏

Section titled “默认侧边栏”

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

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

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

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

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

添加链接和链接分组

Section titled “添加链接和链接分组”

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

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

内部链接

Section titled “内部链接”

使用带有 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 中自定义自动生成的链接”。

内部链接的简易写法

Section titled “内部链接的简易写法”

内部链接也可以通过只提供一个页面 slug 字符串作为简易写法来指定。

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

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

其他链接

Section titled “其他链接”

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

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

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

分组

Section titled “分组”

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

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

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

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

自动生成的链接

Section titled “自动生成的链接”

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

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

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

starlight({
  sidebar: [
    {
      label: '星座',
      // 自动为 'constellations' 目录生成链接。
      items: [{ autogenerate: { directory: 'constellations' } }],
    },
  ],
});

给定以下文件结构：

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

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

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

Section titled “在 frontmatter 中自定义自动生成的链接”

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

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

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

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

徽章

Section titled “徽章”

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

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

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

徽章种类和自定义样式

Section titled “徽章种类和自定义样式”

使用具有 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 属性

Section titled “自定义 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' },
        },
      ],
    },
  ],
});

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

为自动生成的链接自定义 HTML 属性

Section titled “为自动生成的链接自定义 HTML 属性”

通过在 autogenerate 配置中定义 attrs 属性，为所有自动生成的链接自定义 HTML 属性。 单个页面可以使用 sidebar.attrs frontmatter 字段 指定自定义属性，这些属性将与 autogenerate.attrs 配置合并。

例如，使用以下配置：

starlight({
  sidebar: [
    {
      autogenerate: {
        // 自动为 'constellations' 目录生成链接。
        directory: 'constellations',
        // 将所有自动生成链接的标签设为斜体。
        attrs: { style: 'font-style: italic' },
      },
    },
  ],
});

并给定以下的文件结构：

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

将生成以下侧边栏，其中所有自动生成的链接均为斜体：

国际化

Section titled “国际化”

你可以使用链接和分组条目上的 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',
        },
      ],
    },
  ],
});

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

通过内部链接实现国际化

Section titled “通过内部链接实现国际化”

默认情况下，内部链接将从 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。

通过徽章实现国际化

Section titled “通过徽章实现国际化”

对于徽章，text 属性可以是字符串，而对于多语言网站，文本属性则可以是具有每个不同区域设置值的对象。 使用对象形式时，键必须是 BCP-47 标签（例如 en、ar 或 zh-CN）：

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

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

折叠分组

Section titled “折叠分组”

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

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

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

自动生成的子组 也可以通过将 autogenerate.collapsed 属性设置为 true 来默认折叠。

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

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