How to Fix Docusaurus Sidebar Configuration

In this tutorial, you'll learn about How to Fix Docusaurus Sidebar Configuration. We cover key concepts, practical examples, and best practices.

Your Docusaurus sidebar is empty, shows pages in wrong order, or the custom sidebar you defined does not appear. Sidebar configuration in sidebars.js needs correction.

The Wrong Way

module.exports = {
  docs: [
    'intro',
    'getting-started',
    'installation', // 'installation' file does not exist → sidebar breaks silently
  ],
};

Referencing a file that does not exist in the sidebar array causes the entire sidebar to fail.

## The Right Way

### Step 1: Use autogenerated sidebars

```<a href="/programming-languages/javascript/">javascript</a>
// sidebars.js
module.exports = {
  docs: [
    {
      type: 'autogenerated',
      dirName: '.', // generate sidebar from folder structure
    },
  ],
};

This creates a sidebar automatically from the `docs/` directory structure. No manual item listing needed.

### Step 2: Verify file paths match sidebar entries

```javascript
// Manual sidebar — each item must match a file path
module.exports = {
  docs: [
    'intro',                    // docs/intro.md
    {
      type: 'category',
      label: 'Getting Started',
      items: ['getting-started/installation'], // docs/getting-started/installation.md
    },
  ],
};

### Step 3: Handle category order

```<a href="/programming-languages/javascript/">javascript</a>
// Use weight/order in frontmatter for autogenerated sidebars
---
sidebar_position: 1
---

Lower sidebar_position values appear first. Without it, Docusaurus sorts alphabetically.

Step 4: Check sidebar ID

// docusaurus.config.js
module.exports = {
  presets: [
    [
      '"@docusaurus"/preset-classic',
      {
        docs: {
          sidebarPath: require.resolve('./sidebars.js'),
          // "sidebarCollapsible: true" makes categories collapsible
        },
      },
    ],
  ],
};

Sidebar renders correctly — 3 categories, 12 items, installation guide positioned first under "Getting Started".

Prevention

• Start with autogenerated sidebars and only switch to manual when you need custom ordering.
• Run npm run build after sidebar changes to catch configuration errors.
• The autogeneration approach mirrors Doda Browser's bookmark manager — folder structure drives the sidebar automatically.

Common Mistakes with sidebar config

1. Mixing let bindings with <- bindings in do notation, producing type errors
2. Overlapping type class instances that cause GHC to reject the program with ambiguous dispatch errors
3. Non-exhaustive pattern matches that compile with warnings then crash at runtime

These mistakes appear frequently in real-world DOCUSAURUS code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ

items: [
  {
    type: 'category',
    label: 'Level 1',
    items: [
      {
        type: 'category',
        label: 'Level 2',
        items: ['page-at-level-2'],
      },
    ],
  },
];

module.exports = {
  docs: [...],    // sidebar for /docs
  api: [...],     // sidebar for /api
};