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.

---
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.

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:

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

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:

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:

---
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:

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

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.

---
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:

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:

Set features.sidebar: false in astro.config.ts to disable the rail site-wide. See Frontmatter for complete field shapes and badge variants.