Skip to main content

Sidebar items

The Docusaurus sidebar supports multiple item types that let you organize and present documentation in a flexible way. Below are the supported item types:

  • Doc: Link to a single doc page and associate it with a sidebar.
  • Link: Link to any internal or external page.
  • Category: Create a dropdown of sidebar items.
  • Autogenerated: Automatically generate a sidebar slice based on the file system.
  • HTML: Render pure HTML in the sidebar.
  • Ref: Link to a doc page without participating in navigation generation.

The doc type links to a doc page and assigns that page to a sidebar.

type SidebarItemDoc =
  | {
      type: 'doc';
      id: string;
      label?: string;
      key?: string;
      className?: string;
      customProps?: Record<string, unknown>;
    }
  | string; // shorthand

Example:

sidebars.js
export default {
  mySidebar: [
    {
      type: 'doc',
      id: 'getting-started',
      label: 'Getting Started',
    },
    // Shorthand syntax
    'introduction',
  ],
};

Tip: Use sidebar_label or sidebar_custom_props in the doc’s front matter to override labels or add metadata.

The link type links to internal or external pages.

type SidebarItemLink = {
  type: 'link';
  label: string;
  href: string;
  description?: string;
  key?: string;
  className?: string;
  customProps?: Record<string, unknown>;
};

Example:

sidebars.js
export default {
  linksSidebar: [
    {
      type: 'link',
      label: 'Home',
      href: '/',
    },
    {
      type: 'link',
      label: 'GitHub',
      href: 'https://github.com',
    },
  ],
};

The html type renders custom HTML inside a sidebar <li> element.

type SidebarItemHtml = {
  type: 'html';
  value: string;
  defaultStyle?: boolean;
  key?: string;
  className?: string;
  customProps?: Record<string, unknown>;
};

Example:

sidebars.js
export default {
  myHtmlSidebar: [
    {
      type: 'html',
      value: '<strong>Core Concepts</strong>',
      defaultStyle: true,
    },
  ],
};

The category type groups related items and can be collapsible.

type SidebarItemCategory = {
  type: 'category';
  label: string;
  items: SidebarItem[];
  description?: string;
  key?: string;
  className?: string;
  customProps?: Record<string, unknown>;
  collapsible?: boolean;
  collapsed?: boolean;
  link?: SidebarItemCategoryLinkDoc | SidebarItemCategoryLinkGeneratedIndex;
};

Example:

sidebars.js
export default {
  docs: [
    {
      type: 'category',
      label: 'Guides',
      collapsible: true,
      collapsed: false,
      items: [
        'creating-pages',
        {
          type: 'category',
          label: 'Advanced',
          items: ['versioning', 'i18n'],
        },
      ],
    },
  ],
};

A category can link to:

  • Generated index page – auto-creates an index listing all children.
link: {
  type: 'generated-index',
  title: 'Docusaurus Guides',
  description: 'Overview of guides',
  slug: '/category/guides',
}
  • Doc link – link to a specific document.
link: { type: 'doc', id: 'introduction' }

Collapsible and expanded options​

  • collapsible: false → category is fixed open.
  • collapsed: false → expanded by default.

Global defaults can be configured in docusaurus.config.js:

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

Using shorthands​

You can simplify definitions with doc and category shorthand.

Doc shorthand​

sidebars.js
export default {
  sidebar: ['myDoc'],
};

Category shorthand​

sidebars.js
export default {
  sidebar: {
    'Getting Started': ['intro', 'setup'],
    Guides: ['advanced'],
  },
};

This shorthand allows nested categories:

sidebars.js
export default {
  sidebar: {
    Docusaurus: {
      Basics: ['intro', 'setup'],
      Advanced: ['versioning', 'plugins'],
    },
  },
};

These options make Docusaurus sidebars flexible and powerful, letting you mix links, docs, categories, and even custom HTML to create rich navigation experiences.