Skip to main content

Autogenerated

Docusaurus can automatically create a sidebar from your filesystem structure. Each folder becomes a sidebar category, and each file becomes a document link.

type SidebarItemAutogenerated = {
  type: 'autogenerated';
  dirName: string; // Source folder to generate the sidebar slice from (relative to docs)
};

You can generate a full sidebar with just a single configuration:

sidebars.js
export default {
  myAutogeneratedSidebar: [
    {
      type: 'autogenerated',
      dirName: '.', // '.' means the current docs folder
    },
  ],
};

An autogenerated item is converted to a sidebar slice, which is a list of items (doc or category) that Docusaurus builds by scanning your folder. You can splice multiple autogenerated items from different directories and mix them with regular sidebar items.

Example

Consider this folder structure:

docs
├── api
│   ├── product1-api
│   │   └── api.md
│   └── product2-api
│       ├── basic-api.md
│       └── pro-api.md
├── intro.md
└── tutorials
    ├── easy
    │   ├── easy1.md
    │   └── easy2.md
    ├── advanced
    │   ├── advanced1.md
    │   ├── advanced2.md
    │   └── read-more
    │       ├── resource1.md
    │       └── resource2.md
    └── tutorial-end.md

Using an autogenerated sidebar like this:

sidebars.js
export default {
  mySidebar: [
    'intro',
    {
      type: 'category',
      label: 'Tutorials',
      items: [
        {
          type: 'autogenerated',
          dirName: 'tutorials/easy',
        },
        {
          type: 'autogenerated',
          dirName: 'tutorials/advanced',
        },
        'tutorial-end',
      ],
    },
    {
      type: 'autogenerated',
      dirName: 'api',
    },
  ],
};

Will automatically expand into nested categories and docs, matching the file/folder structure—no manual sidebar maintenance required.

Category Index Convention​

Docusaurus can automatically link a category to an index document if it follows one of these patterns:

  • index.md (case-insensitive)
  • README.md (case-insensitive)
  • A file with the same name as the folder

For example, docs/Guides/index.md will be linked automatically.

sidebars.js
export default {
  docs: [
    {
      type: 'category',
      label: 'Guides',
      link: { type: 'doc', id: 'Guides/index' },
      items: [],
    },
  ],
};

If a folder contains only an index file, Docusaurus converts it into a single doc link instead of a collapsible category.

When using autogenerated sidebars, Docusaurus reads sidebar metadata directly from the doc’s front matter.

Doc Metadata​

Inside your markdown files, use:

docs/tutorials/easy1.md
---
sidebar_position: 2
sidebar_label: Easy Tutorial
sidebar_class_name: highlight
---
  • sidebar_position → controls ordering
  • sidebar_label → custom label
  • sidebar_class_name → custom CSS class

Category Metadata​

Create a _category_.json or _category_.yml in a folder:

docs/tutorials/_category_.json
{
  "position": 2.5,
  "label": "Tutorials",
  "collapsible": true,
  "collapsed": false,
  "className": "custom-class",
  "link": {
    "type": "generated-index",
    "title": "Tutorials Overview"
  }
}

Ordering with Number Prefixes​

A quick way to control ordering is to use number prefixes:

docs
├── 01-Intro.md
├── 02-Getting-Started.md
└── 03-Advanced.md

Docusaurus removes the numbers from URLs and labels by default.

Custom Sidebar Generator​

For full control, you can override the sidebar generation:

docusaurus.config.js
export default {
  plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {
        async sidebarItemsGenerator({ defaultSidebarItemsGenerator, ...args }) {
          const items = await defaultSidebarItemsGenerator(args);
          // Example: reverse order
          return items.reverse();
        },
      },
    ],
  ],
};