侧边栏
Mr.Hope 2020-10-13 大约 11 分钟
你需要配置 themeConfig.sidebar，才能在站点中显示侧边栏(Sidebar)。
对于 Sidebar 基本的配置，可以传入一个包含多个链接的数组:
数组的每一项最终都会渲染为一个侧边栏项目。
你可以省略 .md 拓展名，同时以 / 结尾的路径将会被视为 /README.md。
侧边栏默认启用图标支持，将在侧边栏的链接前显示页面的图标 (读取在 frontmatter 中设置的 icon)。你可以在 themeConfig 中将 sidebarIcon 设置为 false 来禁用它。
侧边栏链接的文字将会从页面自动获取 (优先读取在 frontmatter 中设置的标题，然后回退到页面的第一个标题)。如果你想要指定链接的文字，使用一个格式为 [link, text] 的数组。
例子
# 嵌套的标题链接
默认情况下，侧边栏会自动地显示由当前页面的标题(headers)组成的链接，并按照页面本身的结构进行嵌套，你可以通过 themeConfig.sidebarDepth 来修改它的行为。默认的深度(也是最大的深度)是 2，它将提取到 h2 和 h3 的标题，设置成 0 将会禁用标题(headers)链接。
也可以使用 frontmatter 来为某个页面重写此值:
---
sidebarDepth: 2
---
1
2
3
2
3
# 显示所有页面的标题链接
默认情况下，侧边栏只会显示由当前活动页面的标题 (headers) 组成的链接，你可以将 themeConfig.displayAllHeaders 设置为 true 来显示所有页面的标题链接:
# 活动的标题链接
默认情况下，当用户通过滚动查看页面的不同部分时，嵌套的标题链接和 URL 中的 Hash 值会实时更新，这个行为可以通过以下的配置来禁用:
# 侧边栏分组
你可以通过使用对象来将侧边栏划分成多个组。每一个组默认会被渲染成一个可以打开与折叠的菜单，菜单项目是组内通过 children 设置的每个分组链接。
你可以使用 prefix 来为组内的每个链接添加默认的路径前缀，使用 icon 为该分组文字添加一个图标。
侧边栏的每个子组默认是可折叠的，你可以设置 collapsable: false 来让一个组永远都是展开状态。
一个侧边栏的子组配置同时支持 sidebarDepth 字段用于重写默认显示的侧边栏深度(2)。
例子
侧边栏分组也可以进行嵌套:
通常情况下，你可能希望搭配 prefix 使用来快速还原文档的结构。
比如，将你的页面文件为下述的目录结构:
.
├─ README.md
├─ contact.md
├─ about.md
├─ foo/
│ ├─ README.md
│ ├─ one.md
│ └─ two.md
└─ bar/
├─ README.md
├─ three.md
└─ four.md
1
2
3
4
5
6
7
8
9
10
11
12
2
3
4
5
6
7
8
9
10
11
12
你就可以进行以下配置:
注意
在配置侧边栏时请特别注意 / 的添加。处于性能考虑，我们会假设用户对侧边栏进行了正确的配置，所以我们不会对路径进行任何处理和校验(比如遍历生成路径结构进行比对验证)，而是直接拼接生成。
请留心你的配置是否可以拼接成正确的路径。
比如期待 bar/foo/，却因为 bar 缺少尾随 / 而 foo 未配置前置 / 导致生成 barfoo/ 的情况，或两者均配置而生成了错误的 bar//foo。它们都会造成解析错误，导致对应的侧边栏项目缺省。
提示
处于上面的一点原因，我们会在开发服务器的控制台打出任何无法找到对应页面的侧边栏链接。这意味着你的错误配置可以很容易的通过其追踪并修正。
# 多个侧边栏
如果你想为不同的页面组来显示不同的侧边栏，你需要通过 路径前缀: 侧边栏配置 的格式为侧边栏配置一个对象。
比如，将你的页面文件为下述的目录结构:
.
├─ README.md
├─ contact.md
├─ about.md
├─ foo/
│ ├─ README.md
│ ├─ one.md
│ └─ two.md
└─ bar/
├─ README.md
├─ three.md
└─ four.md
1
2
3
4
5
6
7
8
9
10
11
12
2
3
4
5
6
7
8
9
10
11
12
你就可以遵循以下的侧边栏配置，来为不同路径显示不同的分组:
注意
你需要特别注意对象键声明的顺序，通常来说你应该把更精确的路径放置在前边。这是因为 VuePress 会按顺序遍历侧边栏配置的各项键名来寻找匹配的配置，一旦一个键名成功匹配为当前路经，它就会显示对应的侧边栏配置。
在本例中，fallback 侧边栏就是因为这个原因必须在最后定义。
# 自动生成侧栏
如果你希望自动生成一个仅仅包含了当前页面标题(headers)链接的侧边栏，你可以通过 frontmatter 来实现:
---
sidebar: auto
---
1
2
3
2
3
你也可以通过配置来在所有页面中启用它:
# 禁用侧边栏
你可以通过 YAML front matter 来禁用指定页面的侧边栏:
---
sidebar: false
---
1
2
3
2
3
# 多语言
在 多语言 (opens new window) 模式下, 你也可以为某一特定的语言配置侧边栏:
# 博主信息
如果你配置了博客相关选项，你可以通过配置 themeConfig.blog.sidebarDisplay 来决定是否在侧边栏显示博主的名字、头像以及文章与标签的数量。
你可以设置 'mobile' 来只在移动视图显示，或者设置 always，来保持在侧边栏显示。
# sidebarConfig
我们提供了一个 sidebarConfig Helper 函数。你可以从 vuepress-theme-hope 中将其引入，并包裹你的导航栏配置来让编辑器提供自动补全并帮助你校验侧边栏配置是否正确。
提示
当你将 VuePress 配置拆分成多个部分时，你可以使用该 Helper 函数来保持自动补全与校验。