---
title: "Sidebar"
description: "Autogenerate, configure, or transform the sidebar tree with custom groups, links, order, and badges."
---

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

# Sidebar

Nimbus builds a typed sidebar tree from your content. Start with the filesystem, take control with configuration, or transform the final tree for navigation that depends on application data or the current route.

## Generate from the filesystem

The sidebar is generated from `src/content/docs/` by default. Set `sidebar.items` in `astro.config.ts` only when you need to override that structure. Use `sidebar.order` in a page's frontmatter, such as `src/content/docs/get-started.mdx`, to control ordering; otherwise entries are alphabetical.

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

Frontmatter can also hide entries, customize directory groups, redirect links, or collapse a section. See [Per-page controls](#per-page-controls).

## Define the structure

In `astro.config.ts`, use `sidebar.items` when the filesystem should not define the entire rail. Config items can be nested and can mix manual links with generated content:

```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" } },
  ],
},
  ],
}
```

| Shape | Use |
|---|---|
| `"slug"` | Link one page from the primary collection. |
| `{ label, link }` | Add a labeled internal or external link. |
| `{ autogenerate: { directory } }` | Generate a group from one content directory. |
| `{ autogenerate: { collection, prefix? } }` | Mount another registered collection, optionally at a custom URL prefix. |
| `{ label, items }` | Build a recursive manual group. Groups support `collapsed`, `badge`, and `icon`. |
| `{ segment, landing }` | Give a manual group ownership of a URL segment while linking its label and breadcrumbs to a real landing page. |

Array position controls manual item order. Nimbus does not re-sort a configured or transformed array.

## Scope large sidebars

Large sites can progressively narrow the rail:

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

- `scope: "full"` is the default and renders the complete tree on every page.
- `scope: "section"` renders only the active top-level group. Pair it with section tabs or another cross-section navigation surface.
- `isolate.boundaries` descends again when a route matches a segment glob. `*` matches one path segment; non-matching routes are unchanged.
- `defaultCollapsed` closes groups by default. The active group still opens, and a group's explicit `collapsed` value wins.

Build section tabs from the same structural tree:

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

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

## Control group landing pages

A directory `index.mdx` is its group's landing page. Configure how those landings appear across the site in `astro.config.ts`:

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

| Option | Behavior |
|---|---|
| `indexDisplay: "header-link"` | Default. The group heading links to its landing page. |
| `indexDisplay: "overview-leaf"` | The group heading becomes a disclosure and the landing becomes its first child. |
| `overviewLabel: true` | Labels landing links `Overview`. A string supplies a custom label. |
| `sidebar.group.hideIndex: true` | Keeps the page built but makes its group heading non-interactive. |
| `sidebar.hideChildren: true` | Collapses the whole directory to one link to its landing page. |

## Transform the final tree

Configuration defines the structural tree. `getSidebar()` also accepts a synchronous or asynchronous `transform` for computed navigation. It runs after scope and isolation, but before `indexDisplay` reshapes landing pages.

```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,
});
---
```

The callback receives:

| Value | Meaning |
|---|---|
| `tree` | The cloned, active-state-aware `SidebarItem[]` for this page. Nodes are `link`, `external`, or recursive `group` items. |
| `currentSlug` | The complete current URL path. |
| `sectionSlug` | The first path segment. |
| `module` | The second path segment, when present. |
| `indexEntryId` | The active section group's landing entry ID, when it has one. |

A transform can fetch data, insert or remove nodes, rewrite nested groups, attach badges, or reorder the rail. Return rendered `SidebarItem` nodes, not config-only shapes such as `autogenerate`. Preserve existing properties when decorating nodes, and pass the result to `getPrevNext()` when pagination should follow the transformed order.

Transforms only affect the page rail. Breadcrumbs and `getSidebarSections()` continue to use the structural tree.

## Per-page controls

Use frontmatter for local changes:

| Field | Behavior |
|---|---|
| `sidebar: false` | Removes the sidebar column from this page. |
| `sidebar.order` | Orders an entry inside an autogenerated group. |
| `sidebar.label` | Overrides the page title in the rail. |
| `sidebar.badge` | Adds a string or styled badge. |
| `sidebar.hidden` | Builds the page but removes it from the rail. |
| `sidebar.group.label` | Overrides the directory group's label from its `index.mdx`. |
| `sidebar.group.badge` | Adds a badge to the directory group. |
| `sidebar.group.icon` | Adds an `astro-icon` icon to the directory group. |
| `sidebar.group.hideIndex` | Prevents the directory group heading from linking to its index. |
| `sidebar.hideChildren` or `hideChildren` | Collapses the directory to its landing link. |
| `external_link` | Rewrites the sidebar destination to another internal path or an external URL. |

Set `features.sidebar: false` in `astro.config.ts` to disable the rail site-wide. See [Frontmatter](/writing/frontmatter) for complete field shapes and badge variants.

Source: https://docs.klounge.kr/navigation/sidebar/index.mdx