Sidebar using _category_.json files and Customizing Sidebar with sidebars.js.

In Docusaurus, you can create a nested sidebar using _category_.json files. This allows you to organize your documentation into categories and subcategories, which will be reflected in the sidebar structure. Here's a step-by-step guide on how to achieve this:

Step-by-Step Guide

1. Organize Your Documentation Files: Structure your documentation files into folders that represent categories and subcategories.

2. Create _category_.json Files: In each folder that should be treated as a category or subcategory, create a _category_.json file.

3. Define Category Metadata: Inside each _category_.json file, define the metadata for the category. This includes the label (name) of the category and optionally other settings like position, collapsibility, etc.

Example Directory Structure

Here's an example directory structure for nested categories:

docs
├── tutorials
│   ├── _category_.json
│   ├── intro.md
│   ├── advanced
│   │   ├── _category_.json
│   │   ├── topic1.md
│   │   └── topic2.md
│   └── basics
│       ├── _category_.json
│       ├── topic1.md
│       └── topic2.md
└── reference
    ├── _category_.json
    ├── api.md
    └── cli.md

Example _category_.json Files

docs/tutorials/_category_.json:

{
  "label": "Tutorials",
  "position": 1,
  "collapsible": true,
  "collapsed": true
}

docs/tutorials/advanced/_category_.json:

{
  "label": "Advanced Tutorials",
  "position": 2,
  "collapsible": true,
  "collapsed": true
}

docs/tutorials/basics/_category_.json:

{
  "label": "Basics Tutorials",
  "position": 1,
  "collapsible": true,
  "collapsed": true
}

docs/reference/_category_.json:

{
  "label": "Reference",
  "position": 2,
  "collapsible": true,
  "collapsed": true
}

Customizing Sidebar with sidebars.js

Ensure your sidebars.js is configured to automatically include the nested structure:

/**
 * Creating a sidebar enables you to:
 - create an ordered group of docs
 - render a sidebar for each doc of that group
 - provide next/previous navigation

 The sidebars can be generated from the filesystem, or explicitly defined here.

 Create as many sidebars as you want.
 */

// @ts-check

/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
const sidebars = {
  // By default, Docusaurus generates a sidebar from the docs folder structure
  tutorialSidebar: [{type: 'autogenerated', dirName: '.'}],
  
  // But you can create a sidebar manually
  /*
  tutorialSidebar: [
    'intro',
    {
      type: 'category',
      label: 'Tutorial',
      items: ['tutorial-basics/create-a-document'],
    },
  ],
   */
};

module.exports = sidebars;

Step 1: Organize Your Documentation Structure

First, ensure that your documentation files are organized in a hierarchical structure within the docs directory. For example:

my-docusaurus-site/
├── docs/
│   ├── category1/
│   │   ├── doc1.md
│   │   └── doc2.md
│   ├── category2/
│   │   ├── subcategory1/
│   │   │   ├── doc3.md
│   │   │   └── doc4.md
│   │   └── subcategory2/
│   │       ├── doc5.md
│   │       └── doc6.md
│   └── doc7.md

Step 2: Configure Sidebar in sidebars.js

In your sidebars.js file (located in the root of your Docusaurus project or in the sidebars folder), define the nested structure. Here’s an example configuration:

// sidebars.js
module.exports = {
  docs: [
    {
      type: 'category',
      label: 'Category 1',
      items: ['category1/doc1', 'category1/doc2'],
    },
    {
      type: 'category',
      label: 'Category 2',
      items: [
        {
          type: 'category',
          label: 'Subcategory 1',
          items: ['category2/subcategory1/doc3', 'category2/subcategory1/doc4'],
        },
        {
          type: 'category',
          label: 'Subcategory 2',
          items: ['category2/subcategory2/doc5', 'category2/subcategory2/doc6'],
        },
      ],
    },
    'doc7', // top-level document
  ],
};

Step 3: Verify Document IDs

Ensure that the document IDs in the sidebars.js configuration match the paths relative to the docs folder. For example, category1/doc1 corresponds to docs/category1/doc1.md.

Explanation

1. Directory Structure: Organize your documentation into folders. Each folder represents a category or subcategory.
2. category.json: Place a _category_.json file in each folder you want to treat as a category or subcategory.
3. Metadata: Define the label and other properties in _category_.json to customize the appearance and behavior of the category in the sidebar.
4. Autogenerated Sidebar: In sidebars.js, use the autogenerated type to automatically generate the sidebar based on the folder structure and _category_.json files.

By following these steps, you can create a nested sidebar in Docusaurus that organizes your documentation into hierarchical categories and subcategories.