Version: 3.7.0

使用多个侧边栏

¥Using multiple sidebars

你可以为要分组在一起的每组 Markdown 文件创建侧边栏。

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

提示

Docusaurus 网站是使用多个侧边栏的一个很好的例子：

¥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'],
};

当浏览 doc1 或 doc2 时，会显示 tutorialSidebar；当浏览 doc3 或 doc4 时，会显示 apiSidebar。

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

¥Understanding sidebar association

按照上面的示例，如果 commonDoc 包含在两个侧边栏中：

¥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'],
};

Docusaurus 如何知道浏览 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.

当你将文档 Y 添加到侧边栏 X 时，它会创建双向绑定：侧边栏 X 包含文档 Y 的链接，当浏览文档 Y 时，将显示侧边栏 X。但有时，我们想要打破隐式绑定：

¥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:

如何在侧边栏 X 中生成文档 Y 的链接而不使侧边栏 X 显示在 Y 上？例如，当我将 doc Y 包含在多个侧边栏中（如上例所示）时，我想明确告诉 Docusaurus 显示一个侧边栏？

¥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?
如何在浏览文档 Y 时显示侧边栏 X，但侧边栏 X 不应包含指向 Y 的链接？例如，当 Y 是 "文档主页" 并且侧边栏纯粹用于导航时？

¥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 选项 displayed_sidebar 将强制设置侧边栏关联。对于同一个示例，你仍然可以使用 doc 简写，无需任何特殊配置：

¥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
---

它明确告诉 Docusaurus 在浏览 commonDoc 时显示 apiSidebar。使用相同的方法，你可以使不包含文档 Y 的侧边栏 X 出现在文档 Y 上：

¥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
---

即使 tutorialSidebar 不包含 home 的链接，在查看 home 时仍然会显示它。

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

如果设置 displayed_sidebar: null，则此页面上将不会显示任何侧边栏，并且随后也不会显示分页。

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

生成分页

¥Generating pagination

Docusaurus 使用侧边栏在每个文档页面的底部生成 "next" 和 "previous" 分页链接。它严格使用显示的侧边栏：如果没有关联侧边栏，它也不会生成分页。但是，不保证链接为 "next" 和 "previous" 的文档显示相同的侧边栏：它们包含在此侧栏中，但在其前面的内容中，它们可能有不同的 displayed_sidebar。

¥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.

如果通过设置 displayed_sidebar front Matter 显示侧边栏，并且该侧边栏不包含文档本身，则不显示分页。

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

你可以使用前页 pagination_next 和 pagination_prev 自定义分页。考虑这个侧边栏：

¥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',
  ],
};

"windows" 上的分页下一个链接指向 "linux"，但这没有意义：你希望读者在安装后继续进行 "入门"。在这种情况下，你可以手动设置分页：

¥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

你还可以禁用显示带有 pagination_next: null 或 pagination_prev: null 的分页链接。

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

默认情况下，分页标签是侧边栏标签。你可以使用前面的内容 pagination_label 来自定义该文档在分页中的显示方式。

¥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.

`ref` 项目

¥The ref item

ref 类型在各方面都与 doc 型相同，只是它不参与生成导航元数据。它仅将自身注册为链接。当生成分页和显示侧边栏时，ref 项被完全忽略。

¥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.

当你希望从多个侧边栏链接到同一文档时，它特别有用。该文档仅属于一个侧边栏（其注册为 type: 'doc' 或来自自动生成的目录的侧边栏），但其链接将出现在其注册的所有侧边栏中。

¥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'],
};

你可以将 ref 类型视为相当于执行以下操作：

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

将 displayed_sidebar: tutorialSidebar 设置为 commonDoc（侧边栏关联中忽略 ref）

¥Setting displayed_sidebar: tutorialSidebar for commonDoc (ref is ignored in sidebar association)
设置 pagination_next: doc5 为 doc2，设置 pagination_prev: doc2 为 doc5（分页生成时忽略 ref）

¥Setting pagination_next: doc5 for doc2 and setting pagination_prev: doc2 for doc5 (ref is ignored in pagination generation)

了解侧边栏关联​

生成分页​

ref 项目​

了解侧边栏关联

生成分页

`ref` 项目