Skip to main content
Version: 3.2.1

使用多个侧边栏

您可以为每组Markdown文件创建一个侧边栏，以便将它们分组在一起。

tip

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

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

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

  1. 如何在不在Y文档上显示侧边栏X的情况下生成指向Y文档的链接？ 例如，当我在多个侧边栏中包含Y文档时，如上例所示，我想明确告诉Docusaurus显示一个侧边栏？
  2. 如何在浏览文档 Y 时显示侧边栏 X，但侧边栏 X 不应包含指向 Y 的链接？ 例如，当 Y 是“文档主页”且侧边栏仅用于导航时？

前置选项 displayed_sidebar 将强制设置侧边栏关联。对于相同的示例，您仍然可以在没有任何特殊配置的情况下使用文档简写：

sidebars.js
export default {
  tutorialSidebar: {
    'Category 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 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 来禁用显示分页链接。

默认情况下，分页标签是侧边栏标签。您可以使用前置内容 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）