侧边栏 | Nimbus 中文文档

Nimbus 会从你的内容中构建一个类型化的侧边栏树。你可以从文件系统开始，通过配置进行控制，或者在依赖应用数据或当前路由的场景下，转换最终的导航树。

从文件系统生成

侧边栏默认从 src/content/docs/ 生成。只有当你需要覆盖该结构时，才在 astro.config.ts 中设置 sidebar.items。使用页面 frontmatter 中的 sidebar.order（如 src/content/docs/get-started.mdx）来控制排序；否则按字母顺序排列。

src/content/docs/get-started.mdxyaml

---
title: Get started
sidebar:
  order: 1
  label: Quickstart
  badge:
    text: New
    variant: tip
---

frontmatter 还可以隐藏条目、自定义目录分组、重定向链接或折叠某个章节。详见逐页控制。

定义结构

在 astro.config.ts 中，当文件系统不应定义整个导航栏时，使用 sidebar.items。配置项可以嵌套，也可以将手动链接与生成内容混合使用：

astro.config.tsts

sidebar: {
  items: [
    "introduction",
    { label: "GitHub", link: "https://github.com/you/repo" },
    {
      label: "Guides",
      autogenerate: { directory: "guides" },
      collapsed: false,
      badge: "New",
      icon: "ph:book-open",
    },
    {
      label: "API",
      autogenerate: { collection: "api", prefix: "/reference" },
      icon: "ph:code",
    },
    {
      label: "AI",
      segment: "/ai",
      landing: "/ai/models",
      items: [
        { label: "Models", link: "/ai/models" },
        { autogenerate: { directory: "ai/guides" } },
      ],
    },
  ],
}

形式	用途
`"slug"`	链接主内容集合中的单个页面。
`{ label, link }`	添加一个带标签的内部或外部链接。
`{ autogenerate: { directory } }`	从单个内容目录生成分组。
`{ autogenerate: { collection, prefix? } }`	挂载另一个已注册的集合，可选自定义 URL 前缀。
`{ label, items }`	构建递归的手动分组。分组支持 `collapsed`、`badge` 和 `icon`。
`{ segment, landing }`	让手动分组拥有一个 URL 段，同时将其标签和面包屑链接到实际的落地页。

数组位置控制手动项的排序。Nimbus 不会对已配置或已转换的数组重新排序。

范围化大型侧边栏

大型站点可以逐步缩小导航栏的范围：

astro.config.tsts

sidebar: {
  scope: "section",
  isolate: { boundaries: ["learning-paths/*", "reference/*"] },
  defaultCollapsed: true,
}

scope: "full" 是默认值，在每个页面上渲染完整的树。
scope: "section" 仅渲染当前活动的顶级分组。可以搭配章节标签页或其他跨章节导航组件使用。
isolate.boundaries 在路由匹配某个段 glob 时再次向下展开。* 匹配一个路径段；不匹配的路由保持不变。
defaultCollapsed 默认折叠分组。活动分组仍然会展开，且分组上显式设置的 collapsed 值优先。

从相同的结构树构建章节标签页：

---
import { getSidebarSections } from "@cloudflare/nimbus-docs";

const sections = await getSidebarSections(currentSlug, {
  collection: entry.collection,
});
---

控制分组落地页

目录中的 index.mdx 是该分组的落地页。在 astro.config.ts 中配置这些落地页在整个站点中的呈现方式：

astro.config.tsts

sidebar: {
  indexDisplay: "overview-leaf",
  overviewLabel: "Overview",
}

选项	行为
`indexDisplay: "header-link"`	默认值。分组标题链接到其落地页。
`indexDisplay: "overview-leaf"`	分组标题变为展开/折叠按钮，落地页变为其第一个子项。
`overviewLabel: true`	将落地页链接标签设为 `Overview`。传入字符串可自定义标签。
`sidebar.group.hideIndex: true`	保留页面构建，但使其分组标题不可交互。
`sidebar.hideChildren: true`	将整个目录折叠为一个指向落地页的链接。

转换最终树

配置定义了结构树。getSidebar() 还接受一个同步或异步的 transform，用于计算型导航。它在作用域和隔离之后运行，但在 indexDisplay 重塑落地页之前执行。

src/pages/[...slug].astroastro

---
import { getPrevNext, getSidebar } from "@cloudflare/nimbus-docs";

const sidebar = await getSidebar(currentSlug, {
  collection: entry.collection,
  transform: ({ tree, sectionSlug }) => {
    if (sectionSlug !== "api") return tree;

    return tree.map((item) =>
      item.type === "group" && item.label === "Reference"
        ? {
            ...item,
            collapsed: false,
            badge: "API",
            children: [
              ...item.children,
              {
                type: "external",
                label: "API status",
                href: "https://status.example.com",
                order: Number.MAX_SAFE_INTEGER,
              },
            ],
          }
        : item,
    );
  },
});

const prevNext = await getPrevNext(currentSlug, {
  sidebarTree: sidebar,
});
---

回调函数接收以下参数：

值	含义
`tree`	当前页面的已克隆、带活动状态感知的 `SidebarItem[]`。节点类型为 `link`、`external` 或递归的 `group`。
`currentSlug`	完整的当前 URL 路径。
`sectionSlug`	第一个路径段。
`module`	第二个路径段（如果存在）。
`indexEntryId`	活动章节分组的落地页条目 ID（如果存在）。

转换函数可以获取数据、插入或移除节点、重写嵌套分组、附加徽章或重新排序导航栏。返回渲染后的 SidebarItem 节点，而不是仅含配置的形式（如 autogenerate）。装饰节点时保留现有属性，当分页需要跟随转换后的顺序时，将结果传递给 getPrevNext()。

转换仅影响页面导航栏。面包屑和 getSidebarSections() 继续使用结构树。

逐页控制

使用 frontmatter 进行局部修改：

字段	行为
`sidebar: false`	从此页面移除侧边栏列。
`sidebar.order`	在自动生成的分组中排序条目。
`sidebar.label`	覆盖导航栏中的页面标题。
`sidebar.badge`	添加字符串或带样式的徽章。
`sidebar.hidden`	构建页面但从导航栏中移除它。
`sidebar.group.label`	从其 `index.mdx` 覆盖目录分组的标签。
`sidebar.group.badge`	为目录分组添加徽章。
`sidebar.group.icon`	为目录分组添加 `astro-icon` 图标。
`sidebar.group.hideIndex`	阻止目录分组标题链接到其索引页。
`sidebar.hideChildren` 或 `hideChildren`	将目录折叠为其落地页链接。
`external_link`	将侧边栏目标重写为其他内部路径或外部 URL。

在 astro.config.ts 中设置 features.sidebar: false 可全局禁用导航栏。详见 Frontmatter 了解完整的字段格式和徽章变体。