10.侧边栏导航

套用主题

欢迎来到我的网站

Starlight 提供了一整套选项来自定义侧边栏布局和内容。

默认侧边栏

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

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

Directorysrc/
- Directorycontent/
  - Directorydocs/
    Directoryguides/
    components.md
    i18n.md
    Directoryreference/
    configuration.md

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

Directoryguides
- Components
- Internationalization (i18n)
Directoryreference
- Configuration Reference

添加链接和链接分组

请在 astro.config.mjs 中使用 starlight.sidebar 属性。

链接

使用具有 label 和 link 属性的对象添加一个指向内部或外部页面的链接。

starlight({
  sidebar: [
    // 指向 CSS & Styling 指南的链接
    { label: 'CSS & Styling', link: '/zh-cn/guides/css-and-tailwind/' },
    // 指向 Astro 官网的外部链接
    { label: 'Astro', link: 'https://astro.build/' },
  ],
});

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

CSS & Styling
Astro

分组

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

starlight({
  sidebar: [
    // 一个名为 "Guides" 的链接分组
    {
      label: 'Guides',
      items: [
        { label: 'Components', link: '/guides/components/' },
        { label: 'Internationalization (i18n)', link: '/guides/i18n/' },
        // 一个嵌套的链接分组
        {
          label: 'Styling',
          items: [
            { label: 'CSS', link: '/guides/css-and-tailwind/' },
            { label: 'Tailwind', link: '/guides/css-and-tailwind/' },
            { label: 'Shiki', link: '/guides/css-and-tailwind/' },
          ],
        },
      ],
    },
  ],
});

自动生成的分组

在侧边栏中自动生成一个分组 , 默认情况下，页面按照文件 slug¹ 的字母顺序排序。

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

starlight({
  sidebar: [
    {
      label: 'Guides',
      // 自动生成一个链接分组，用于 'guides' 目录。
      autogenerate: { directory: 'guides' },
    },
  ],
});

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

在单个页面的 frontmatter 中使用 sidebar 字段来自定义自动生成的链接。允许你设置自定义标签或者为链接添加徽章，隐藏侧边栏中的链接，或者定义自定义排序权重。

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

徽章

链接、分组、自动生成的分组都可以包含一个 badge 属性，以在它们的标签旁边显示徽章。 (注意: badge的位置)

starlight({
  sidebar: [
    {
      label: 'Guides',
      items: [
        // 带有 "New" 徽章的链接。
        {
          label: 'Components',
          link: '/guides/components/',
          badge: 'New',
        },
      ],
    },
    // 一个带有 "Deprecated" 徽章的自动生成分组。
    {
      label: 'Reference',
      badge: 'Deprecated',
      autogenerate: { directory: 'reference' },
    },
  ],
});

徽章种类

badge内部可以是字典 : badge: { text: 'Experimental', variant: 'caution' },

自定义 HTML 属性

在链接对象里添加 attrs 属性来自定义链接元素的 HTML 属性。

例如,让链接打开新标签页:

starlight({
  sidebar: [
    {
      label: 'Guides',
      items: [
        // 一个指向 Astro 文档的在新标签页打开的外部链接。
        {
          label: 'Astro Docs',
          link: 'https://docs.astro.build/',
          attrs: { target: '_blank', style: 'font-style: italic' },
        },
      ],
    },
  ],
});

折叠分组

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

starlight({
  sidebar: [
    {
      label: 'Guides',
      // 默认折叠分组
      collapsed: true,
      items: [
        { label: 'Components', link: '/guides/components/' },
        { label: 'Internationalization (i18n)', link: '/guides/i18n/' },
      ],
    },
  ],
});

自动生成的分组遵循其父级分组的 collapsed 值：

starlight({
  sidebar: [
    {
      label: 'Guides',
      // 默认折叠分组及其自动生成的子组。
      collapsed: true,
      autogenerate: { directory: 'guides' },
    },
  ],
});

即 true 表示不显示组内资源

类型： string , 从内容文件名生成的页面 slug。 ↩