侧边栏导航
一个组织良好的侧边栏是优秀文档的关键,因为它是用户浏览网站的主要方式之一。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 中自定义自动生成的链接
标题为“在 frontmatter 中自定义自动生成的链接”的部分在单个页面中使用 sidebar
frontmatter 字段 来自定义自动生成的链接。
侧边栏 frontmatter 选项允许您设置自定义标签、使用自定义属性、为链接添加徽章、从侧边栏隐藏链接,或定义自定义排序权重。
---title: My pagesidebar: # 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 属性
标题为“为自动生成的链接自定义 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 }, }, ],});
上述配置生成以下侧边栏: