Skip to main content

Sidebar Configuration

Learn how to configure sidebars in Docusaurus to organize your documentation.

Overview​

Sidebars are configured in sidebars.js and control the left navigation panel when viewing documentation pages.

Basic Structure​

const sidebars = {
  tutorialSidebar: [
    'intro',
    {
      type: 'category',
      label: 'Getting Started',
      items: ['getting-started/index'],
    },
  ],
};

module.exports = sidebars;

1. Autogenerated Sidebar​

Automatically generates sidebar from folder structure:

codeHtmlSidebar: [{ 
  type: 'autogenerated', 
  dirName: 'code/html' 
}],

Benefits:

  • Automatically includes all markdown files in the directory
  • Maintains alphabetical order
  • No manual updates needed when adding new files

Best for: Sections with many files that follow a consistent structure

2. Manual Sidebar​

Explicitly define the sidebar structure:

tutorialSidebar: [
  'intro',
  {
    type: 'category',
    label: 'Guides',
    items: [
      'guides/pages',
      'guides/docs/create-a-doc',
    ],
  },
],

Benefits:

  • Full control over order and nesting
  • Can add custom labels
  • Can include links to external resources

Best for: Sections requiring specific ordering or custom organization

3. Category with Toggles​

Create collapsible categories in the sidebar:

visualEditingSidebar: [
  'design-editing/index',
  {
    type: 'category',
    label: 'Guidelines',
    link: {type: 'doc', id: 'design-editing/guidelines/index'},
    collapsible: true,
    collapsed: false,
    items: [
      'design-editing/guidelines/web-design',
      'design-editing/guidelines/logo-design',
      'design-editing/guidelines/video-editing',
    ],
  },
],

Linking Sidebars to Navbar​

Each sidebar must be referenced in the navbar configuration:

In sidebars.js:

wpGeneratepressSidebar: [{ 
  type: 'autogenerated', 
  dirName: 'wordpress/generatepress' 
}],

In docusaurus.config.js:

{
  'type': 'doc',
  'docId': 'wordpress/generatepress/index',
  'sidebarId': 'wpGeneratepressSidebar',  // Must match sidebar name
  'label': 'Generatepress'
}

Naming Conventions​

Use camelCase for sidebar IDs:

// Good
codeHtmlSidebar
wpGeneratepressSidebar
visualEditingCanvaSidebar

// Avoid
code-html-sidebar
wp_generatepress_sidebar

Creating Isolated Sidebars​

To create separate sidebars for each menu item (like the Code menu structure):

  1. Create directories for each section
  2. Add index.md files to each directory
  3. Define sidebars in sidebars.js:
codeHtmlSidebar: [{ type: 'autogenerated', dirName: 'code/html' }],
codeCssSidebar: [{ type: 'autogenerated', dirName: 'code/css' }],
codePhpSidebar: [{ type: 'autogenerated', dirName: 'code/php' }],
  1. Link in navbar:
{
  'type': 'dropdown',
  'label': 'Code',
  'items': [
    { 'type': 'doc', 'docId': 'code/html/index', 'sidebarId': 'codeHtmlSidebar', 'label': 'HTML' },
    { 'type': 'doc', 'docId': 'code/css/index', 'sidebarId': 'codeCssSidebar', 'label': 'CSS' },
    { 'type': 'doc', 'docId': 'code/php/index', 'sidebarId': 'codePhpSidebar', 'label': 'PHP' },
  ]
}

Common Patterns​

Pattern 1: Simple Section​

// Directory: docs/ai/platform/
aiPlatformSidebar: [{ 
  type: 'autogenerated', 
  dirName: 'ai/platform' 
}],

Pattern 2: Multi-Level Section​

// Directory: docs/wordpress/generatepress/
wpGeneratepressSidebar: [{ 
  type: 'autogenerated', 
  dirName: 'wordpress/generatepress' 
}],

Pattern 3: Custom Ordered Section​

tutorialSidebar: [
  'intro',
  {
    type: 'category',
    label: 'Getting Started',
    items: ['getting-started/index'],
  },
  {
    type: 'link',
    label: 'Blog',
    href: '/blog',
  },
],

Troubleshooting​

Warning: No docs found​

Error: [WARNING] No docs found in "wordpress/generatepress": can't auto-generate a sidebar.

Cause: The directory exists but has no markdown files.

Solution: Create at least an index.md file:

sudo tee /opt/docker-data/apps/docusaurus/site/docs/wordpress/generatepress/index.md <<EOF
# Generatepress

Documentation for Generatepress.