使用多个侧边栏

你可以为每一组希望组合在一起的 Markdown 文件创建一个侧边栏。

提示

道格龙（Docusaurus）官网本身就是使用多个侧边栏的一个很好的例子：

思考以下这个例子：

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

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

沿用上面的例子，如果 commonDoc 被同时包含在了两个侧边栏中：

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

道格龙（Docusaurus）如何知道在浏览 commonDoc 时应该显示哪个侧边栏呢？答案是：它不知道，并且我们不保证它会选择哪一个。

当你将文档 Y 添加到侧边栏 X 时，就创建了一个双向绑定：侧边栏 X 包含一个指向文档 Y 的链接，并且在浏览文档 Y 时，会显示侧边栏 X。但有时，我们希望打破这种隐式绑定：

我如何在侧边栏 X 中生成一个指向文档 Y 的链接，但又不在 Y 页面上显示侧边栏 X？ 例如，像上例那样，我将文档 Y 包含在了多个侧边栏中，并且我想明确告诉道格龙（Docusaurus）应该显示哪一个。
我如何让侧边栏 X 在浏览文档 Y 时显示，但侧边栏 X 本身不包含指向 Y 的链接？ 例如，当 Y 是一个"文档主页"，而侧边栏纯粹用于导航时。

头部元数据选项 displayed_sidebar 会强制设置侧边栏的关联。对于相同的例子，你仍然可以无需任何特殊配置就使用文档简写：

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

然后添加一个头部元数据：

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

这就明确地告诉道格龙（Docusaurus），在浏览 commonDoc 时要显示 apiSidebar。使用同样的方法，你可以让一个不包含文档 Y 的侧边栏 X 显示在文档 Y 的页面上：

home.md
---
displayed_sidebar: tutorialSidebar
---

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

如果你设置了 displayed_sidebar: null，那么在这个页面上将不会显示任何侧边栏，也因此不会有分页导航。

生成分页导航

道格龙（Docusaurus）利用侧边栏在每个文档页面的底部生成"上一页"和"下一页"的分页导航链接。它严格使用当前显示的侧边栏：如果没有关联的侧边栏，它也不会生成分页导航。然而，被链接为"上一页"和"下一页"的文档不保证会显示同一个侧边栏：它们虽然被包含在这个侧边栏中，但在它们的头部元数据里，可能会有不同的 displayed_sidebar 设置。

如果一个侧边栏是通过设置 displayed_sidebar 头部元数据显示的，而这个侧边栏本身不包含当前文档，那么将不会显示分页导航。

你可以通过头部元数据 pagination_next 和 pagination_prev 来自定义分页导航。考虑下面这个侧边栏：

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

在 "windows" 页面上，分页导航的"下一页"链接会指向 "linux"，但这并不合理：你可能希望读者在安装后直接进入"快速入门"。在这种情况下，你可以手动设置分页导航：

windows.md
---
pagination_next: getting-started
---

# 在 Windows 上安装

你也可以使用 pagination_next: null 或 pagination_prev: null 来禁用显示某个分页链接。

分页链接的标签默认是侧边栏的标签。你可以使用头部元数据 pagination_label 来自定义该文档在分页导航中的显示方式。

`ref` 项目类型

ref 类型与 doc 类型在各方面都完全相同，唯一的区别是它不参与生成导航元数据。它只注册自己为一个链接。在生成分页导航和显示侧边栏时，ref 类型的项目会被完全忽略。

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

思考以下这个例子：

sidebars.js
export default {
  tutorialSidebar: {
    '分类 A': [
      'doc1',
      'doc2',
      {type: 'ref', id: 'commonDoc'},
      'doc5',
    ],
  },
  apiSidebar: ['doc3', 'doc4', 'commonDoc'],
};

你可以将 ref 类型理解为等同于执行了以下操作：

为 commonDoc 设置 displayed_sidebar: tutorialSidebar（ref 在侧边栏关联中被忽略）
为 doc2 设置 pagination_next: doc5，并为 doc5 设置 pagination_prev: doc2（ref 在分页导航生成中被忽略）

理解侧边栏关联​

生成分页导航​

ref 项目类型​

理解侧边栏关联

生成分页导航

`ref` 项目类型