跳到主要内容
版本：3.8.1

使用多个侧边栏

你可以为每个想要分组的Markdown文件集创建一个侧边栏。

提示

Docusaurus 站点是使用多个侧边栏的良好示例

考虑这个例子

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

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

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

  1. 如何在侧边栏 X 中生成指向文档 Y 的链接，而不让侧边栏 X 在 Y 上显示？ 例如，当我像上面的例子那样将文档 Y 包含在多个侧边栏中时，并且我想明确告诉 Docusaurus 显示一个侧边栏？
  2. 如何让侧边栏 X 在浏览文档 Y 时显示，但侧边栏 X 不应包含指向 Y 的链接？ 例如，当 Y 是一个“文档主页”并且侧边栏纯粹用于导航时？

Front matter 选项 displayed_sidebar 将强制设置侧边栏关联。对于同一个例子，你仍然可以使用文档简写而无需任何特殊配置

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

然后添加一个 front matter

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

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

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

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

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

生成分页​

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

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

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

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

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

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

# Installation on Windows

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

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

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 在分页生成中被忽略）