Sidebar

The sidebar is generated from the page tree, which in turn comes from the folder structure and meta.json manifests described in Writing Content. This page covers the behaviours layered on top of that tree.

Root folders#

A folder with "root": true in its meta.json becomes a sidebar root. When the tree contains roots, the top of the sidebar shows a switcher with one entry per root (icon and title), and only the active root's children are listed below it. Pages that belong to no root are shown when no root is active. The folder's description is carried on the tree node for custom switchers but is not rendered by the built-in one.

{
  "title": "SDK",
  "description": "Client libraries for every platform.",
  "icon": "Package",
  "root": true
}

{
  "title": "CLI",
  "description": "Commands and flags.",
  "icon": "Terminal",
  "root": true
}

Use roots to split a large site into products, platforms, or audiences, the same way header tabs do but driven by content instead of config. Header tabs and roots compose: a tab can point at the first page of a root.

Versioning#

Give root a string instead of true to mark roots of the same type. Roots that share a type are interchangeable: when a reader switches from one to another, the sidebar keeps the relative path if the target root has the same page.

{ "title": "v2", "root": "version", "defaultOpen": true }

{ "title": "v1", "root": "version" }

Reading /docs/v2/guides/auth and switching to v1 lands on /docs/v1/guides/auth when that file exists, and on the v1 index otherwise. The helpers behind this are exported from the root entry (getRootFolders, getActiveRoot, getSidebarNodes, projectUrlToRoot) if you build a custom switcher.

Open state#

Which folders start expanded is decided in this order:

1. The folder containing the current page is always open.
2. A folder with defaultOpen in its meta.json uses that value.
3. Otherwise, folders at depth sidebar.defaultOpenLevel or shallower start open. The default is 0, so only folders that set defaultOpen begin expanded.

sidebar: {
  defaultOpenLevel: 1,
},

Folders with "collapsible": false always show their children and render without a chevron.

Prefetching#

Sidebar links use next/link, which prefetches the target route when it enters the viewport. On very large sites that can mean a lot of requests; turn it off with sidebar: { prefetch: false }. Navigation still works the same, it just fetches on click.

Icons#

Pages set icon in frontmatter and folders set icon in meta.json. Values are names from the bundled icon set in PascalCase (BookOpen) or kebab-case (book-open). Icons are resolved once on the server, so the tree passed to the client stays serializable. Separators and link items take an icon through the [Icon] prefix in meta.json:

"pages": ["---[Compass]Navigation---", "[Rocket][Changelog](/changelog)"]

This site's sidebar uses all three: folder icons, icon separators in the Components section, and an external link item under API Reference.

Mobile#

Below 768px the sidebar is hidden and opens from the hamburger button in the header as a right-side drawer with the same tree, switcher, and open state.

Sidebar footer#

DocsLayout accepts a sidebarFooter node rendered at the bottom of the desktop sidebar, for example a version badge or a link to the changelog:

<DocsLayout tree={tree} config={config} sidebarFooter={<span>v1.0</span>}>
  {children}
</DocsLayout>