Customizing the Sidebar

The sidebar is a critical navigation element in your Docusaurus site. This guide explains how to customize its appearance and behavior to enhance your documentation's user experience.

Sidebar Configuration Options

Docusaurus offers several ways to configure your sidebar, both functionally and visually:

Basic Sidebar Structure

Sidebar configuration is typically done in sidebars.js or in TypeScript projects, sidebars.ts:

module.exports = {
  mySidebar: [
    {
      type: 'category',
      label: 'Getting Started',
      items: ['introduction', 'installation'],
    },
    {
      type: 'doc',
      id: 'configuration',
    },
  ],
};

Auto-generated Sidebars

For simpler projects, you can use auto-generated sidebars:

module.exports = {
  tutorialSidebar: [{type: 'autogenerated', dirName: '.'}],
};

Visual Customization

Styling with CSS

You can customize the sidebar's appearance by overriding Docusaurus CSS variables in your src/css/custom.css file:

:root {
  /* Sidebar width */
  --doc-sidebar-width: 300px;
  
  /* Sidebar colors */
  --ifm-menu-color: #5c5c5c;
  --ifm-menu-color-active: #2e8555;
  
  /* Sidebar padding */
  --ifm-menu-link-padding-vertical: 0.5rem;
  --ifm-menu-link-padding-horizontal: 0.75rem;
}

Category Styling

You can also customize how categories appear in the sidebar:

.menu__list-item-collapsible {
  font-weight: bold;
}

.menu__list .menu__list {
  padding-left: 0.75rem;
}

Advanced Sidebar Customization

For more advanced customization, you can:

1. Swizzle Sidebar Components: Customize React components used by the sidebar
2. Create Custom Navigation: Build entirely custom navigation components
3. Use Category Metadata: Add _category_.json files to folders for more control

Example Category Configuration

Create a _category_.json file in your docs folder:

{
  "label": "My Custom Category",
  "position": 2,
  "link": {
    "type": "generated-index",
    "description": "Custom description for this category"
  },
  "collapsed": false
}

Font Matter

You can add styling to the top of a doc file

---
title: Install with Collabora
sidebar_position: 2
tags:
   - Docker
   - Docker Compose
   - Tutorial
keywords: [Docker, Docker Engine, Tutorial, Nextcloud]
last_update:
  author: BankaiTech
---
Some Doc Content

Changing the doc name shown in the Sidebar

title: Doc Name

Changing the order of the Doc files

sidebar_position: 2

Showing when the docs were last updated and by who (via github)

last_update:
  author: BankaiTech

Sidebar Organization Best Practices

• Limit sidebar nesting to 2-3 levels for better readability
• Use consistent naming conventions for categories and documents
• Order items from most general to most specific
• Ensure category labels are concise and descriptive

Resources

• Official Sidebar Documentation
• Sidebar Item Types - All available sidebar item configurations
• Category Metadata - Using category.json for sidebar organization
• Autogenerated Sidebar - Details on generating sidebar from folder structure
• GitHub Discussion: Sidebar Best Practices - Community discussion on sidebar organization