跳转到内容
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 控制侧边栏外观的更多详细信息，请参阅“自定义自动生成的链接”。

标题为“内部链接的简写”的部分

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

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

starlight({
  sidebar: ['constellations/andromeda', 'constellations/orion'],
});
标题为“其他链接”的部分

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

starlight({
  sidebar: [
    // A link to a non-docs page on this site.
    { label: 'Meteor Store', link: '/shop/' },
    // An external link to the NASA website.
    { label: 'NASA', link: 'https://www.nasa.gov/' },
  ],
});

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

分组

标题为“分组”的部分

您可以通过将相关链接分组到一个可折叠的标题下，为侧边栏添加结构。分组可以包含链接和其他子分组。

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

starlight({
  sidebar: [
    // A group of links labelled "Constellations".
    {
      label: 'Constellations',
      items: [
        'constellations/carina',
        'constellations/centaurus',
        // A nested group of links for seasonal constellations.
        {
          label: 'Seasonal',
          items: [
            'constellations/andromeda',
            'constellations/orion',
            'constellations/ursa-minor',
          ],
        },
      ],
    },
  ],
});

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

自动生成的分组

标题为“自动生成的分组”的部分

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

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

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

starlight({
  sidebar: [
    {
      label: 'Constellations',
      // Autogenerate a group of links for the 'constellations' directory.
      autogenerate: { directory: 'constellations' },
    },
  ],
});

以及以下文件结构：

  • 目录src/
    • 目录content/
      • 目录docs/
        • 目录constellations/
          • carina.md
          • centaurus.md
          • 目录seasonal/
            • andromeda.md

将生成以下侧边栏：

标题为“在 frontmatter 中自定义自动生成的链接”的部分

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

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

src/content/docs/example.md
---
title: My page
sidebar:
  # Set a custom label for the link
  label: Custom sidebar label
  # Set a custom order for the link (lower numbers are displayed higher up)
  order: 2
  # Add a badge to the link
  badge:
    text: New
    variant: tip
---

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

徽章

标题为“徽章”的部分

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

starlight({
  sidebar: [
    {
      label: 'Stars',
      items: [
        // A link with a "Supergiant" badge.
        {
          slug: 'stars/persei',
          badge: 'Supergiant',
        },
      ],
    },
    // An autogenerated group with an "Outdated" badge.
    {
      label: 'Moons',
      badge: 'Outdated',
      autogenerate: { directory: 'moons' },
    },
  ],
});

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

徽章变体和自定义样式

标题为“徽章变体和自定义样式”的部分

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

text 代表要显示的内容（例如“新”）。默认情况下，徽章将使用您网站的主题色。要使用内置的徽章样式，请将 variant 属性设置为以下值之一：note、tip、danger、caution 或 success。

或者，您可以通过将 class 属性设置为一个 CSS 类名来创建自定义徽章样式。

starlight({
  sidebar: [
    {
      label: 'Stars',
      items: [
        // A link with a yellow "Stub" badge.
        {
          slug: 'stars/sirius',
          badge: { text: 'Stub', variant: 'caution' },
        },
      ],
    },
  ],
});

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

了解更多关于使用和自定义徽章的信息。

自定义 HTML 属性

标题为“自定义 HTML 属性”的部分

链接还可以包含一个 attrs 属性，以向链接元素添加自定义 HTML 属性。

在以下示例中，attrs 用于添加 target="_blank" 属性，使链接在新标签页中打开，并应用自定义 style 属性使链接标签变为斜体：

starlight({
  sidebar: [
    {
      label: 'Resources',
      items: [
        // An external link to the NASA website opening in a new tab.
        {
          label: 'NASA',
          link: 'https://www.nasa.gov/',
          attrs: { target: '_blank', style: 'font-style: italic' },
        },
      ],
    },
  ],
});

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

标题为“为自动生成的链接自定义 HTML 属性”的部分

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

例如，使用以下配置：

starlight({
  sidebar: [
    {
      label: 'Constellations',
      autogenerate: {
        // Autogenerate a group of links for the 'constellations' directory.
        directory: 'constellations',
        // Italicize all link labels in this group.
        attrs: { style: 'font-style: italic' },
      },
    },
  ],
});

以及以下文件结构：

  • 目录src/
    • 目录content/
      • 目录docs/
        • 目录constellations/
          • carina.md
          • centaurus.md
          • 目录seasonal/
            • andromeda.md

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

国际化

标题为“国际化”的部分

在链接和分组条目上使用 translations 属性，为每种支持的语言翻译链接或分组的标签。通过指定一个 BCP-47 语言标签（例如 "en"、"ar" 或 "zh-CN"）作为键，并将翻译后的标签作为值。label 属性将用于默认语言环境和没有翻译的语言。

starlight({
  sidebar: [
    {
      label: 'Constellations',
      translations: {
        'pt-BR': 'Constelações',
      },
      items: [
        {
          label: 'Andromeda',
          translations: {
            'pt-BR': 'Andrômeda',
          },
          slug: 'constellations/andromeda',
        },
        {
          label: 'Scorpius',
          translations: {
            'pt-BR': 'Escorpião',
          },
          slug: 'constellations/scorpius',
        },
      ],
    },
  ],
});

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

标题为“内部链接的国际化”的部分

内部链接 默认会自动使用来自内容 frontmatter 的已翻译页面标题。

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

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

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

徽章的国际化

标题为“徽章的国际化”的部分

对于徽章，text 属性可以是一个字符串，或者对于多语言网站，可以是一个为每个不同语言环境提供值的对象。当使用对象形式时，键必须是 BCP-47 标签（例如 en、ar 或 zh-CN）。

starlight({
  sidebar: [
    {
      label: 'Constellations',
      translations: {
        'pt-BR': 'Constelações',
      },
      items: [
        {
          slug: 'constellations/andromeda',
          badge: {
            text: {
              en: 'New',
              'pt-BR': 'Novo',
            },
          },
        },
      ],
    },
  ],
});

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

折叠分组

标题为“折叠分组”的部分

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

starlight({
  sidebar: [
    {
      label: 'Constellations',
      // Collapse the group by default.
      collapsed: true,
      items: ['constellations/andromeda', 'constellations/orion'],
    },
  ],
});

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

自动生成的分组 会遵循其父分组的 collapsed 值。

starlight({
  sidebar: [
    {
      label: 'Constellations',
      // Collapse the group and its autogenerated subgroups by default.
      collapsed: true,
      autogenerate: { directory: 'constellations' },
    },
  ],
});

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

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

starlight({
  sidebar: [
    {
      label: 'Constellations',
      // Do not collapse the "Constellations" group but collapse its
      // autogenerated subgroups.
      collapsed: false,
      autogenerate: { directory: 'constellations', collapsed: true },
    },
  ],
});

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