版本：3.5.2

使用多个侧边栏

您可以为每个想要组合在一起的Markdown 文件集创建一个侧边栏。

提示

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

文档
API

考虑以下示例

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

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

根据以上示例，如果commonDoc包含在两个侧边栏中

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

Docusaurus 如何知道在浏览commonDoc时显示哪个侧边栏？答案：它不知道，我们也不保证它会选择哪个侧边栏。

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

如何在侧边栏 X 中生成到文档 Y 的链接，而不显示侧边栏 X？例如，当我在上述示例中将文档 Y 包含在多个侧边栏中时，并且我想明确告诉 Docusaurus 显示一个侧边栏？
如何在浏览文档 Y 时显示侧边栏 X，但侧边栏 X 不应包含到 Y 的链接？例如，当 Y 是“文档主页”并且侧边栏仅用于导航时？

前置 matter 选项displayed_sidebar将强制设置侧边栏关联。对于相同的示例，您仍然可以使用文档简写，无需任何特殊配置

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

然后添加前置 matter

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

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

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

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

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

生成分页

Docusaurus 使用侧边栏在每个文档页面底部生成“下一个”和“上一个”分页链接。它严格使用显示的侧边栏：如果未关联任何侧边栏，则也不会生成分页。但是，链接为“下一个”和“上一个”的文档并不保证显示相同的侧边栏：它们包含在此侧边栏中，但在其前置 matter 中，它们可能具有不同的displayed_sidebar。

如果通过设置displayed_sidebar前置 matter 来显示侧边栏，并且此侧边栏不包含文档本身，则不会显示分页。

您可以使用前置 matter pagination_next和pagination_prev自定义分页。考虑以下侧边栏

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

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

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

# Installation on Windows

您还可以使用pagination_next: null或pagination_prev: null禁用显示分页链接。

分页标签默认情况下是侧边栏标签。您可以使用前置 matter pagination_label自定义此文档在分页中的显示方式。

`ref` 项目

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

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

考虑以下示例

sidebars.js
export default {
  tutorialSidebar: {
    'Category 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` 项目