Skip to main content

Sidebar Config

The file sidebars.ts controls your documentation sidebar — the list of pages on the left side of every docs page.

This page shows you how to structure it.

File Location​

sidebars.ts

Located in the project root.

Basic Structure​

import type { SidebarsConfig } from '@docusaurus/plugin-content-docs';

const sidebars: SidebarsConfig = {
  mainSidebar: [
    'intro',
    {
      type: 'category',
      label: 'Getting Started',
      collapsed: false,
      items: [
        'getting-started/index',
        'getting-started/installation',
        'getting-started/local-setup',
        'getting-started/cloud-setup',
      ],
    },
    'changelog',
  ],
};

export default sidebars;

How it works:

  • Each string is a doc ID — the path to a Markdown file, without .md
  • Each object with type: 'category' is a category — a group of docs
  • label — the category name shown in the sidebar
  • items — the docs inside the category

Doc IDs​

A doc ID is the path to a Markdown file, without the .md extension.

FileDoc ID
docs/intro.mdintro
docs/getting-started/index.mdgetting-started/index
docs/getting-started/installation.mdgetting-started/installation
docs/configuration/docusaurus-config.mdconfiguration/docusaurus-config

Folder structure maps to doc IDs. If you move a file, its ID changes.

Categories​

Categories group docs together:

{
  type: 'category',
  label: 'Getting Started',
  collapsed: false,
  items: [...],
}
FieldWhat It Does
labelCategory name
collapsedfalse = open by default, true = closed
itemsDocs inside the category

By default, categories are not clickable — they just expand/collapse. To make a category clickable, add a link:

{
  type: 'category',
  label: 'Getting Started',
  link: {
    type: 'doc',
    id: 'getting-started/index',
  },
  items: [...],
}

Or use an auto-generated index:

{
  type: 'category',
  label: 'Getting Started',
  link: {
    type: 'generated-index',
    title: 'Getting Started with Nocturne',
    description: 'Install Nocturne, run it locally, and deploy your site.',
  },
  items: [...],
}

Nested Categories​

Categories can be nested:

{
  type: 'category',
  label: 'Configuration',
  items: [
    {
      type: 'category',
      label: 'Advanced',
      items: [
        'configuration/advanced/caching',
        'configuration/advanced/redirects',
      ],
    },
    'configuration/docusaurus-config',
  ],
}

Limit nesting to 2 levels — deeper nesting is hard to navigate.

Ordering​

Docs appear in the sidebar in the order you list them in items. The sidebar_position field in each Markdown file is ignored when you use a manual sidebars.ts.

Example:

items: [
  'getting-started/installation',    // appears first
  'getting-started/local-setup',     // appears second
  'getting-started/cloud-setup',     // appears third
],

Multiple Sidebars​

You can have multiple sidebars. Example: one for docs, one for API reference:

const sidebars: SidebarsConfig = {
  docsSidebar: [...],
  apiSidebar: [...],
};

Then in each doc's frontmatter:

---
sidebar: apiSidebar
---

For most projects, one sidebar is enough.

Auto-Generated Sidebar​

Instead of manually listing docs, you can let Docusaurus build the sidebar from your folder structure:

const sidebars: SidebarsConfig = {
  mainSidebar: [{ type: 'autogenerated', dirName: '.' }],
};

Pros: Less maintenance. Cons: Less control over order and labels.

Nocturne uses a manual sidebar for full control.

Adding a New Doc​

  1. Create the Markdown file in docs/
  2. Add its doc ID to sidebars.ts
  3. Save and run npm start

Example:

// Add to items array
items: [
  'getting-started/installation',
  'getting-started/local-setup',
  'getting-started/new-page',        // ← new
],

Removing a Doc​

  1. Remove its doc ID from sidebars.ts
  2. Delete the Markdown file (or move it elsewhere)

If you remove the ID but keep the file, the doc still exists but won't appear in the sidebar.

Troubleshooting​

"These sidebar document ids do not exist"​

A doc ID in sidebars.ts doesn't match any file. Check:

  1. Spelling of the ID
  2. File exists in docs/
  3. File has the correct .md extension

Category is not clickable​

Add a link field to the category — see Category Links.

Docs appear in the wrong order​

The order in items is the order in the sidebar. Reorder the array.

  1. Save the file
  2. Restart the dev server
  3. Check the terminal for errors

What's Next?​

Now let's configure Decap CMS.

👉 Next: Decap CMS →