跳到主要内容
版本:Canary 🚧

使用多个侧边栏

你可以为每组想要分类到一起的 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'],
};

Docusaurus 该怎么知道在浏览 commonDoc 的时候展示哪个侧边栏呢? 答案是:它不知道,我们也不能保证它会选哪个侧边栏。

当你在侧边栏甲中添加一篇文档乙的时候,会创建一个双向绑定:侧边栏甲会包含一个指向乙的链接,并且当浏览乙的时候,甲会被显示。 但是有时候,我们会想要解除这两重绑定关系中的一重。比如:

  1. _怎么在侧边栏甲中生成一个文档乙的链接,但不要在浏览乙的时候显示甲?_比如,当我像上文的例子一样,有若干个侧边栏都包含了文档乙的时候,我希望能明确告诉 Docusaurus 显示其中某个侧边栏?
  2. _怎么在浏览文档乙的时候显示侧边栏甲,但甲不包含乙的链接?_比如,如果乙是「文档总览页」,而侧边栏这时候只是用来导航的?

前言的 displayed_sidebar 字段会强制设置侧边栏的绑定。 继续用上文的例子,你仍然可以用简写形式,不需要任何特别配置:

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

然后加一段前言:

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

这会显式地告诉 Docusaurus,在浏览 commonDoc 的时候,显示 apiSidebar。 用同样的方法,你可以让不包含文档乙的侧边栏甲在文档乙上显示:

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

即便 tutorialSidebar 不包含指向 home 的链接,tutorialSidebar 还是会在浏览 home 的时候显示。

如果你设置了 displayed_sidebar: null,这一页就不会显示任何侧边栏了,因此也不会有分页导航了。

生成分页导航

Docusaurus 会用侧边栏信息,在每一页文档的末尾生成「下一页」和「上一页」的导航链接。 它严格地使用当前显示的侧边栏:如果没有绑定的侧边栏,它也不会生成分页导航。 然而,链接到的「下一篇」和「上一篇」文档并不保证会显示相同的侧边栏:它们被包含在了这个侧边栏里,但它们的前言里可能有另一个 displayed_sidebar

如果一个侧边栏是因为设置了 displayed_sidebar 前言而被显示的,而侧边栏并不包含这个文档本身,那么也不会显示分页导航。

你可以用 pagination_nextpagination_prev 自定义分页导航。 考虑这个侧边栏:

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

"windows" 页面上的分页链接会指向 "linux",但这没有意义:你应该想让读者在安装完毕后继续阅读「上手」。 在这种情况下,你可以手动设置分页导航:

windows.md
---
pagination_next: 上手
---

# Windows 安装

你也可以用 pagination_next: null 或者 pagination_prev: null 禁用分页链接。

分页链接的标签默认为侧边栏标签。 你可以用 pagination_label 前言自定义这篇文档应该如何在分页链接中显示。

ref 类型与 doc 类型 几乎一模一样,唯一的区别就是它不参与生成导航元数据。 它只会注册一个链接。 在生成分页显示侧边栏时,ref 项目会被完全忽略。

当你想要从若干个侧边栏链接到同一篇文档时,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 会在生成分页导航时被忽略)