---
slug: /sidebar/multiple-sidebars
---

# 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](../../../introduction.mdx)
- [API](../../../cli.mdx)

:::

Consider this example:

```js title="sidebars.js"
module.exports = {
  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 {#sidebar-association}

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

```js title="sidebars.js"
module.exports = {
  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:

```js title="sidebars.js"
module.exports = {
  tutorialSidebar: {
    'Category A': ['doc1', 'doc2'],
  },
  apiSidebar: ['doc3', 'doc4'],
};
```

And then add a front matter:

```md title="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:

```md title="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 {#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:

```js title="sidebars.js"
module.exports = {
  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:

```md title="windows.md"
---
# highlight-next-line
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 {#sidebar-item-ref}

The `ref` type is identical to the [`doc` type](./items.mdx#sidebar-item-doc) in every way, except that it doesn't participate in generating navigation metadata. It only registers itself as a link. When [generating pagination](#generating-pagination) and [displaying sidebar](#sidebar-association), `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:

```js title="sidebars.js"
module.exports = {
  tutorialSidebar: {
    'Category A': [
      'doc1',
      'doc2',
      // highlight-next-line
      {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)
