跳转到内容

侧边栏导航

一个组织良好的侧边栏是优秀文档的关键,因为它是用户浏览网站的主要方式之一。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 推断出的值,您可以添加 labeltranslationsattrs 属性。

有关从页面 frontmatter 控制侧边栏外观的更多详细信息,请参阅“自定义自动生成的链接”

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

例如,以下配置等同于上面使用 slug 的配置:

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

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

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/' },
],
});

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

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

使用带有 labelitems 属性的对象添加一个分组。`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 按字母顺序排序。

使用带有 labelautogenerate 属性的对象添加一个自动生成的分组。您的 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' },
},
],
});

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

使用带有 textvariantclass 属性的对象自定义徽章样式。

text 代表要显示的内容(例如“新”)。默认情况下,徽章将使用您网站的主题色。要使用内置的徽章样式,请将 variant 属性设置为以下值之一:notetipdangercautionsuccess

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

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

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

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

链接还可以包含一个 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' },
},
],
},
],
});

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

通过在 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/intropt-br/intro 的页面,在配置侧边栏时,slug 是 intro

对于徽章text 属性可以是一个字符串,或者对于多语言网站,可以是一个为每个不同语言环境提供值的对象。当使用对象形式时,键必须是 BCP-47 标签(例如 enarzh-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 },
},
],
});

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