Using multiple sidebars

You can create a sidebar for each set of Markdown files that you want to group together.

tip

The Docusaurus site is a good example of using multiple sidebars:

• Docs
• API

Consider this example:

sidebars.js

export default {
  tutorialSidebar: {
    'Category A': ['doc1', 'doc2'],
  },
  apiSidebar: ['doc3', 'doc4'],
};

When browsing doc1 or doc2, the tutorialSidebar will be displayed; when browsing doc3 or doc4, the apiSidebar will be displayed.

Understanding sidebar association

Following the example above, if a commonDoc is included in both sidebars:

sidebars.js

export default {
  tutorialSidebar: {
    'Category A': ['doc1', 'doc2', 'commonDoc'],
  },
  apiSidebar: ['doc3', 'doc4', 'commonDoc'],
};

How does Docusaurus know which sidebar to display when browsing commonDoc? Answer: it doesn't, and we don't guarantee which sidebar it will pick.

When you add doc Y to sidebar X, it creates a two-way binding: sidebar X contains a link to doc Y, and when browsing doc Y, sidebar X will be displayed. But sometimes, we want to break either implicit binding:

1. How do I generate a link to doc Y in sidebar X without making sidebar X displayed on Y? For example, when I include doc Y in multiple sidebars as in the example above, and I want to explicitly tell Docusaurus to display one sidebar?
2. How do I make sidebar X displayed when browsing doc Y, but sidebar X shouldn't contain the link to Y? For example, when Y is a "doc home page" and the sidebar is purely used for navigation?

Front matter option displayed_sidebar will forcibly set the sidebar association. For the same example, you can still use doc shorthands without any special configuration:

sidebars.js

export default {
  tutorialSidebar: {
    'Category A': ['doc1', 'doc2'],
  },
  apiSidebar: ['doc3', 'doc4'],
};

And then add a front matter:

commonDoc.md

---
displayed_sidebar: apiSidebar
---

Which explicitly tells Docusaurus to display apiSidebar when browsing commonDoc. Using the same method, you can make sidebar X which doesn't contain doc Y appear on doc Y:

home.md

---
displayed_sidebar: tutorialSidebar
---

Even when tutorialSidebar doesn't contain a link to home, it will still be displayed when viewing home.

If you set displayed_sidebar: null, no sidebar will be displayed whatsoever on this page, and subsequently, no pagination either.

Generating pagination

Docusaurus uses the sidebar to generate the "next" and "previous" pagination links at the bottom of each doc page. It strictly uses the sidebar that is displayed: if no sidebar is associated, it doesn't generate pagination either. However, the docs linked as "next" and "previous" are not guaranteed to display the same sidebar: they are included in this sidebar, but in their front matter, they may have a different displayed_sidebar.

If a sidebar is displayed by setting displayed_sidebar front matter, and this sidebar doesn't contain the doc itself, no pagination is displayed.

You can customize pagination with front matter pagination_next and pagination_prev. Consider this sidebar:

sidebars.js

export default {
  tutorial: [
    'introduction',
    {
      installation: ['windows', 'linux', 'macos'],
    },
    'getting-started',
  ],
};

The pagination next link on "windows" points to "linux", but that doesn't make sense: you would want readers to proceed to "getting started" after installation. In this case, you can set the pagination manually:

windows.md

---
pagination_next: getting-started
---

# Installation on Windows

You can also disable displaying a pagination link with pagination_next: null or pagination_prev: null.

The pagination label by default is the sidebar label. You can use the front matter pagination_label to customize how this doc appears in the pagination.

The ref item

The ref type is identical to the doc type in every way, except that it doesn't participate in generating navigation metadata. It only registers itself as a link. When generating pagination and displaying sidebar, ref items are completely ignored.

It is particularly useful where you wish to link to the same document from multiple sidebars. The document only belongs to one sidebar (the one where it's registered as type: 'doc' or from an autogenerated directory), but its link will appear in all sidebars that it's registered in.

Consider this example:

sidebars.js

export default {
  tutorialSidebar: {
    'Category A': [
      'doc1',
      'doc2',
      {type: 'ref', id: 'commonDoc'},
      'doc5',
    ],
  },
  apiSidebar: ['doc3', 'doc4', 'commonDoc'],
};

You can think of the ref type as the equivalent to doing the following:

• Setting displayed_sidebar: tutorialSidebar for commonDoc (ref is ignored in sidebar association)
• Setting pagination_next: doc5 for doc2 and setting pagination_prev: doc2 for doc5 (ref is ignored in pagination generation)