Skip to main content

📚 Sidebar

A sidebar helps users navigate through related documentation in a structured and interactive way.
It allows you to:

  • Group multiple related documents into a hierarchical tree
  • Display a common sidebar on each of those documents
  • Provide paginated navigation with Next and Previous buttons

1️⃣ Enable Sidebars in Configuration​

To use sidebars in your CodeHarborHub Docs,
you need to define a sidebars.js file and reference it inside your docusaurus.config.js:

docusaurus.config.js
export default {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          sidebarPath: './sidebars.js',
        },
      },
    ],
  ],
};
Node.js Runtime

The sidebars.js file runs in Node.js. This means you cannot use browser APIs, React, or JSX inside it.

2️⃣ Default Sidebar​

If you don’t specify a sidebarPath, Docusaurus will automatically generate a sidebar from your docs folder structure:

sidebars.js
export default {
  mySidebar: [
    {
      type: 'autogenerated',
      dirName: '.', // Generate sidebar from the entire docs folder
    },
  ],
};

This is perfect for quick setups or when your folder hierarchy matches your desired sidebar structure.

A sidebar is a hierarchy of categories, doc links, and external links. It can be defined in two ways:

type Sidebar =
  // Normal syntax
  | SidebarItem[]
  // Shorthand syntax
  | {[categoryLabel: string]: SidebarItem[]};

Example:​

sidebars.js
export default {
  mySidebar: [
    {
      type: 'category',
      label: 'Getting Started',
      items: [
        {
          type: 'doc',
          id: 'create-doc',
        },
      ],
    },
    {
      type: 'category',
      label: 'CodeHarborHub Docs',
      items: [
        { type: 'doc', id: 'docs-introduction' },
        { type: 'doc', id: 'sidebar/index' },
      ],
    },
    {
      type: 'link',
      label: 'Learn More',
      href: 'https://codeharborhub.github.io',
    },
  ],
};

This creates a sidebar with:

  • Two categories: Getting Started and CodeHarborHub Docs
  • One external link to the CodeHarborHub site.

A single sidebars.js file can contain multiple sidebar objects:

type SidebarsFile = {
  [sidebarID: string]: Sidebar;
};

4️⃣ Theme Configuration Options​

You can customize the appearance and behavior of sidebars through themeConfig:

Hideable Sidebar​

Allow users to toggle the entire sidebar:

docusaurus.config.js
export default {
  themeConfig: {
    docs: {
      sidebar: {
        hideable: true,
      },
    },
  },
};

Auto-collapse Categories​

Automatically collapse sibling categories when a new one is opened:

docusaurus.config.js
export default {
  themeConfig: {
    docs: {
      sidebar: {
        autoCollapseCategories: true,
      },
    },
  },
};

5️⃣ Styling & Custom Props​

Add CSS Classes​

Apply custom styles to specific sidebar items using className:

{
  type: 'doc',
  id: 'create-doc',
  className: 'sidebar-item--highlighted',
};

Add Custom Props​

Pass extra data to sidebar items using customProps (useful if you swizzle sidebar React components):

{
  type: 'doc',
  id: 'create-doc',
  customProps: {
    badges: ['new', 'featured'],
    featured: true,
  },
};

Unique Keys​

Provide a unique key to prevent translation conflicts or identify specific items:

{
  type: 'category',
  label: 'API',
  key: 'api-category-v1',
};
Why use key?

Docusaurus uses the key to generate unique i18n translation keys. This avoids conflicts when two sidebar items share the same label.

Breadcrumbs appear at the top of each doc page, reflecting the current sidebar path. To disable them:

docusaurus.config.js
export default {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          breadcrumbs: false,
        },
      },
    ],
  ],
};

7️⃣ Complex Example​

Here’s a real-world sidebar example from the CodeHarborHub project:

sidebars.js
export default {
  docsSidebar: [
    {
      type: 'category',
      label: 'Introduction',
      items: ['docs-introduction', 'create-doc'],
    },
    {
      type: 'category',
      label: 'Guides',
      items: [
        'sidebar/index',
        'sidebar/autogenerated',
        {
          type: 'link',
          label: 'GitHub Repository',
          href: 'https://github.com/CodeHarborHub/codeharborhub.github.io',
        },
      ],
    },
  ],
};

With these options, you can build simple or highly customized navigation trees that make your CodeHarborHub documentation easy to explore and user-friendly.