mirror of
https://github.com/facebook/docusaurus.git
synced 2025-04-28 17:57:48 +02:00
143 lines
5.3 KiB
Text
143 lines
5.3 KiB
Text
---
|
|
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"
|
|
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 {#sidebar-association}
|
|
|
|
Following the example above, if a `commonDoc` is included in both sidebars:
|
|
|
|
```js title="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:
|
|
|
|
```js title="sidebars.js"
|
|
export default {
|
|
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"
|
|
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:
|
|
|
|
```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"
|
|
export default {
|
|
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)
|