侧边栏导航
一个组织良好的侧边栏是良好文档的关键,因为它是用户浏览你的站点的主要方式之一。Starlight 提供了一整套选项来自定义侧边栏布局和内容。
默认侧边栏
默认情况查下,Starlight 会根据你的文档文件系统结构自动生成侧边栏,使用每个文件的 title
属性作为侧边栏条目。
例如,给定以下文件结构:
文件夹src/
文件夹content/
文件夹docs/
文件夹constellations/
- andromeda.md
- orion.md
文件夹stars/
- betelgeuse.md
将会自动生成以下侧边栏:
在 自动生成的分组 章节了解更多关于自动生成侧边栏的内容。
添加链接和链接分组
要配置侧边栏 链接 和 链接分组(在可折叠的标题中),请在 astro.config.mjs
中使用 starlight.sidebar
属性。
结合使用链接和链接分组,你可以创建各种侧边栏布局。
链接
使用具有 label
和 link
属性的对象添加一个指向内部或外部页面的链接。
上面的配置生成以下侧边栏:
分组
你可以通过在可折叠的标题下将相关链接组合在一起来为侧边栏添加结构。 分组可以包含链接和其他子组。
使用具有 label
和 items
属性的对象添加一个分组。
label
将用作分组的标题。
将链接或子组添加到 items
数组中。
上面的配置生成以下侧边栏:
自动生成的分组
Starlight 可以根据文档目录在侧边栏中自动生成一个分组。当你不想手动输入分组中的每个侧边栏项目时,这很有用。
默认情况下,页面按照文件 slug
的字母顺序排序。
使用具有 label
和 autogenerate
属性的对象添加自动生成的分组。autogenerate
的配置必须指定用于侧边栏条目的 directory
。例如,使用以下配置:
给定以下文件结构:
文件夹src/
文件夹content/
文件夹docs/
文件夹constellations/
- carina.md
- centaurus.md
文件夹seasonal/
- andromeda.md
将会自动生成以下侧边栏:
在 frontmatter 中自定义自动生成的链接
在单个页面中使用 sidebar
frontmatter 字段 来自定义自动生成的链接。
侧边栏 frontmatter 选项允许你设置 自定义标签 或者为链接添加 徽章,隐藏 侧边栏中的链接,或者定义 自定义排序权重。
一个包含上面 frontmatter 的页面的自动生成分组将会生成以下侧边栏:
徽章
链接、分组、自动生成的分组都可以包含一个 badge
属性,以在它们的标签旁边显示徽章。
以上配置将生成以下侧边栏:
徽章种类
使用具有 text
和 variant
属性的对象自定义徽章样式。
text
属性表示要显示的内容(例如 “New”)。
通过将 variant
属性设置为以下值之一:note
、tip
、danger
、caution
或 success
,可以覆盖 default
样式,默认样式使用你的网站的强调色。
以上配置将生成以下侧边栏:
自定义 HTML 属性
可以通过在链接对象里添加 attrs
属性来自定义链接元素的 HTML 属性。
在下面的例子中,通过 attrs
添加了一个 target="_blank"
属性,使得链接在新标签页中打开,并应用了一个自定义的 style
属性使链接标签变为斜体:
以上配置将生成以下侧边栏:
国际化
你可以使用链接和分组条目上的 translations
属性,通过指定 BCP-47 语言标签,为每种支持的语言翻译链接或分组标签,例如用 "en"
、"ar"
或 "zh-CN"
作为键,翻译后的标签作为值。
label
属性将用于默认语言和没有翻译的语言。
浏览巴西葡萄牙语文档将生成以下侧边栏:
折叠分组
链接分组可以通过将 collapsed
属性设置为 true
来默认折叠。
以上配置将生成以下侧边栏:
自动生成的分组 遵循其父级分组的 collapsed
值:
以上配置将生成以下侧边栏:
这个行为可以通过定义 autogenerate.collapsed
属性来覆盖。
以上配置将生成以下侧边栏: