---
title: "侧边栏"
description: "自动生成、配置或转换侧边栏树，支持自定义分组、链接、排序和徽章。"
---

> Documentation Index
> Fetch the complete documentation index at: https://nimbus-docs.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 侧边栏

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

<h2 id="generate-from-the-filesystem">从文件系统生成</h2>

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

```yaml title="src/content/docs/get-started.mdx"
---
title: Get started
sidebar:
  order: 1
  label: Quickstart
  badge:
text: New
variant: tip
---
```

frontmatter 还可以隐藏条目、自定义目录分组、重定向链接或折叠某个章节。详见 [逐页控制](#per-page-controls)。

<h2 id="define-the-structure">定义结构</h2>

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

```ts title="astro.config.ts"
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 不会对已配置或已转换的数组重新排序。

<h2 id="scope-large-sidebars">范围化大型侧边栏</h2>

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

```ts title="astro.config.ts"
sidebar: {
  scope: "section",
  isolate: { boundaries: ["learning-paths/*", "reference/*"] },
  defaultCollapsed: true,
}
```

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

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

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

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

<h2 id="control-group-landing-pages">控制分组落地页</h2>

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

```ts title="astro.config.ts"
sidebar: {
  indexDisplay: "overview-leaf",
  overviewLabel: "Overview",
}
```

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

<h2 id="transform-the-final-tree">转换最终树</h2>

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

```astro title="src/pages/[...slug].astro"
---
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()` 继续使用结构树。

<h2 id="per-page-controls">逐页控制</h2>

使用 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](/writing/frontmatter) 了解完整的字段格式和徽章变体。

Source: https://nimbus-docs.cn/navigation/sidebar/index.mdx