Sidebar Configuration in Docusaurus

Sidebars are how your readers navigate docs. They sit on the left, show a tree of pages, and you get two approaches: let Docusaurus generate one from your folder structure, or hand-craft every item yourself.

Sidebar Types

Autogenerated Sidebars

Easiest option. Point Docusaurus at your docs/ folder and it builds the sidebar for you:

Your folder structure *becomes* your sidebar structure:

Visual Result: The sidebar displays a hierarchical tree matching your folder structure. Each folder becomes a collapsible category, and each .mdx file becomes a clickable nav item. Items are ordered by sidebar_position frontmatter or alphabetically.

Category Metadata with _category_.json

You can control how each folder shows up as a category:

Manual Sidebars

When you want full control over what shows up and in what order, define every item yourself:

Sidebar Item Types

Doc Items

The most common type — it links to a document:

Doc IDs come from the file path relative to docs/:

• docs/intro.mdx → ID: intro
• docs/guides/advanced.mdx → ID: guides/advanced
• Or override with id frontmatter

Category Items

Group related docs under a collapsible section:

Category Links

Categories can link to a page, or just expand/collapse:

Visual Result: With generated-index, clicking the category name shows an auto-generated page listing all items in that category as cards with their descriptions.

Link Items

For external URLs or internal links that aren't docs:

HTML Items

Arbitrary HTML — great for separators, section headers, or badges:

Collapsible Categories

You can control expand/collapse behavior globally and per-category:

Per-category override in sidebars.js:

:::tip[Sidebar UX] Use autoCollapseCategories: true for large sidebars with many categories. This keeps the sidebar compact by only showing one expanded category at a time — similar to an accordion pattern. :::

Sidebar Position via Frontmatter

The easiest way to order items in autogenerated sidebars — just add sidebar_position to your frontmatter:

Frontmatter Sidebar Fields

Numbering Strategy

:::note[Position Gaps] Leave gaps in your numbering (10, 20, 30) to make it easy to insert new pages later without renumbering everything:

:::

Number Prefixes (Alternative)

Instead of frontmatter, you can prefix your file names with numbers:

Docusaurus strips the numeric prefix from the URL slug, so 01-intro.mdx becomes /docs/intro.

Custom Sidebar Items

Conditional Items Based on Environment

Want something to only show in dev mode? Since sidebars.js is plain JavaScript, you can do this:

Dynamic Sidebar Generation

You can also read the filesystem at build time and generate sidebar entries automatically:

Multiple Sidebars

Got a big site? You can define separate sidebars for different sections:

Linking to Different Sidebars from Navbar

Wire each sidebar to a navbar item:

Visual Result: The navbar shows separate "Docs", "API", and "Community" links. Clicking each one displays that section with its own sidebar navigation. The left sidebar completely changes based on which section is active.

Controlling Which Sidebar a Doc Shows

Use displayed_sidebar frontmatter to override:

Complete sidebars.js Example

Here's a production-ready config that combines multiple techniques:

Best Practices

:::tip[Sidebar Guidelines]

1. Start with autogenerated — Switch to manual only when you need more control
2. Use sidebar_position — Easier to maintain than manual sidebar ordering
3. Keep depth ≤ 3 levels — Deeply nested sidebars are hard to navigate
4. Use generated index pages — They create useful overview pages for free
5. Add HTML separators — Visual sections make large sidebars scannable
6. Multiple sidebars for large sites — Don't force everything into one sidebar
7. Test on mobile — Sidebars become hamburger menus; keep labels short
8. Leave position gaps — Use 10, 20, 30 instead of 1, 2, 3 for future flexibility

:::

A well-structured sidebar is the difference between docs people love and docs people fight with. Spend time on it — it's the map your readers use to find things.