Skip to main content
WebsiteGitHub last commitGitHub commit activityGitHub IssuesDocker PullsDiscordLocalized

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.

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
  • 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​

Buy me a beer

Changelog

Update MDX syntax to follow Docusaurus best practices


💬 Discord Community Chat

Join the conversation! Comments here sync with our Discord community.

💬 Recent Comments

Loading comments...