Sidebar

The sidebar lists every guide in content/, in the order your meta.json files give. This page covers how it behaves and what you can add around the page tree. To order pages and folders, see Navigation.

Configure the sidebarCopy Anchor Link

import { defineConfig } from '@orbitdocs/next/config';

export default defineConfig({
  site: { title: 'Acme' },
  layout: {
    sidebar: {
      collapsible: true,
      defaultOpenLevel: 1,
      prefetch: true,
      banner: 'You are reading the v2 docs',
    },
  },
});

• defaultOpenLevel opens folders down to that depth on first load. 0 keeps every folder closed; 1 opens top-level folders.
• collapsible lets readers collapse the sidebar on desktop.
• prefetch prefetches the pages the sidebar links to, so they open faster. It uses Next's automatic prefetching, which works on a server and in a static export. Set it to false to turn prefetching off.
• banner is plain text (no Markdown) shown above the page tree. Use it for a version notice or a short hint.
• enabled: false hides the sidebar in every layout. See Pages without a sidebar.

Pages without a sidebarCopy Anchor Link

layout: {
  sidebar: { enabled: false },
},

On wide screens there is no sidebar, and no empty column for it: pages use the width. Small screens keep the menu button and its drawer, because that is where the header links go on a phone.

orbitdocs check and the docs app's server log print a warning for the combinations that lose navigation. The navigation.sidebar links and sidebar.banner only show in the small-screen menu.

Add links under the page treeCopy Anchor Link

navigation.sidebar adds links at the bottom of the sidebar. Use it for support, status or community links.

navigation: {
  sidebar: [
    { text: 'Support', url: 'mailto:help@acme.com', icon: 'LifeBuoy' },
    { text: 'Status', url: 'https://status.acme.com', icon: 'Activity' },
    { text: 'Changelog', url: '/changelog', icon: 'ScrollText' },
  ],
},

icon is a Lucide icon name (LifeBuoy or life-buoy), or a Simple Icons brand name with the Si prefix (SiDiscord). Absolute URLs open in a new tab.

These links show in the notebook, docs and flux layouts.

Show root folders as tabsCopy Anchor Link

Large docs often split into sections such as "Guides", "SDKs" and "Platform". Each section is a root folder: a folder whose meta.json has "root": true. Fumadocs then shows only the current section in the sidebar and lists every section as a tab.

{
  "title": "SDKs",
  "root": true,
  "pages": ["index", "typescript", "python"]
}

layout.tabMode decides where the tabs go:

Other layouts show root folders their own way and ignore tabMode.

Choose the tabsCopy Anchor Link

By default there is one tab per root folder. layout.tabs replaces them with your own list, or turns them off with false:

layout: {
  tabs: [
    { title: 'Guides', url: '/guides', icon: 'BookOpen' },
    { title: 'SDKs', url: '/sdks', icon: 'Package', description: 'TypeScript and Python' },
  ],
},

A tab is active on its URL and every page under it. With private docs, a tab whose page a reader can't open is left out.

Sidebar optionsCopy Anchor Link

Go further in codeCopy Anchor Link

Some sidebar options take React: a banner or footer with links and components, your own page tree items, tabs with custom icons. Set them in lib/overrides.tsx of the docs app. They are merged over the config, so everything else stays as configured.

import type { OrbitOverrides } from '@orbitdocs/next';

export const overrides: OrbitOverrides = {
  layout: {
    sidebar: {
      // Replace layout.sidebar.banner and the navigation.sidebar links.
      banner: <a href="https://v1.docs.acme.com" className="text-sm">Looking for v1?</a>,
      footer: <p className="text-xs">© Acme</p>,
    },
    // Change the root-folder tabs, or pass your own list.
    tabs: { transform: (tab) => ({ ...tab, description: undefined }) },
  },
};

Fumadocs' glass sidebar takes none of the sidebar props. A component used here that runs in the browser (state, effects, event handlers) needs 'use client' at the top of its file.

Next stepsCopy Anchor Link