跳到主要内容
版本：3.5.2

使用多个侧边栏

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

提示

Docusaurus 就是使用多侧边栏的典范之一：

考虑这个例子：

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.

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? 答案是：它不知道，我们也不能保证它会选哪个侧边栏。

当你在侧边栏甲中添加一篇文档乙的时候，会创建一个双向绑定：侧边栏甲会包含一个指向乙的链接，并且当浏览乙的时候，甲会被显示。 但是有时候，我们会想要解除这两重绑定关系中的一重。比如：

  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. 继续用上文的例子，你仍然可以用简写形式，不需要任何特别配置：

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

然后加一段前言：

commonDoc.md
---
displayed_sidebar: apiSidebar
---

Which explicitly tells Docusaurus to display apiSidebar when browsing commonDoc. 用同样的方法，你可以让不包含文档乙的侧边栏甲在文档乙上显示：

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 会用侧边栏信息，在每一页文档的末尾生成「下一页」和「上一页」的导航链接。 它严格地使用当前显示的侧边栏：如果没有绑定的侧边栏，它也不会生成分页导航。 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. 考虑这个侧边栏：

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

"windows" 页面上的分页链接会指向 "linux"，但这没有意义：你应该想让读者在安装完毕后继续阅读「上手」。 在这种情况下，你可以手动设置分页导航：

windows.md
---
pagination_next: 上手
---

# Windows 安装

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

分页链接的标签默认为侧边栏标签。 You can use the front matter pagination_label to customize how this doc appears in the pagination.

The ref type is identical to the doc type in every way, except that it doesn't participate in generating navigation metadata. 它只会注册一个链接。 When generating pagination and displaying sidebar, ref items are completely ignored.

当你想要从若干个侧边栏链接到同一篇文档时，ref 会很有用。 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.

考虑这个例子：

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)