侧边栏
概述
侧边栏是文档常见的页面导航方式，可以快速定位到文档内容。
主题提供了两种方式配置侧边栏：
- 通过主题配置的
sidebar选项配置侧边栏 - 在 类型为
doc的集合 中配置侧边栏
文件结构与基础配置
目录结构设计
典型的项目结构可能如下：
basic.md
types.md
tuple.md
struct.md
README.md# 站点首页
通过sidebar 配置
这种方式适用于简单小巧的文档站点。
.vuepress/config.ts
import { defineUserConfig } from 'vuepress'
import { plumeTheme } from 'vuepress-theme-plume'
export default defineUserConfig({
theme: plumeTheme({
sidebar: {
'/typescript/': [
'basic',
'types'
],
'/rust/': [
'tuple',
'struct'
]
}
})
}).vuepress/plume.config.ts
import { defineThemeConfig } from 'vuepress-theme-plume'
export default defineThemeConfig({
sidebar: {
'/typescript/': [
'basic',
'types'
],
'/rust/': [
'tuple',
'struct'
]
}
})通过 collection 配置 推荐
collections （集合）可以灵活的组织和管理站点中的不同类别的文档，这种方式适用于复杂的站点。
.vuepress/config.ts
import { defineUserConfig } from 'vuepress'
import { plumeTheme } from 'vuepress-theme-plume'
export default defineUserConfig({
theme: plumeTheme({
collections: [
{
type: 'doc',
dir: 'typescript',
linkPrefix: '/typescript/',
title: 'TypeScript 文档',
sidebar: ['basic', 'types'],
},
{
type: 'doc',
dir: 'rust',
linkPrefix: '/rust/',
title: 'Rust 文档',
sidebar: ['tuple', 'struct'],
}
],
})
}).vuepress/plume.config.ts
import { defineThemeConfig } from 'vuepress-theme-plume'
export default defineThemeConfig({
collections: [
{
type: 'doc',
dir: 'typescript',
linkPrefix: '/typescript/',
title: 'TypeScript 文档',
sidebar: ['basic', 'types'],
},
{
type: 'doc',
dir: 'rust',
linkPrefix: '/rust/',
title: 'Rust 文档',
sidebar: ['tuple', 'struct'],
}
],
})配置时机建议
在创建文档文件前完成集合（collection）配置。主题的 auto-frontmatter 功能会根据配置自动生成永久链接和侧边栏结构。
进阶配置管理
模块化配置方案
对于复杂项目，推荐使用主题提供的类型安全配置工具：
.vuepress/collections.ts
import { defineCollection, defineCollections } from 'vuepress-theme-plume'
// 单个集合配置
const typescript = defineCollection({
type: 'doc',
dir: 'typescript',
title: 'TypeScript 文档',
linkPrefix: '/typescript/',
sidebar: [
'guide/intro.md',
'guide/getting-start.md',
'config/config-file.md',
]
})
// 导出所有集合配置
export default defineCollections([
typescript
]).vuepress/config.ts
import { defineUserConfig } from 'vuepress'
import { plumeTheme } from 'vuepress-theme-plume'
import collections from './collections'
export default defineUserConfig({
theme: plumeTheme({
collections
}),
})大型项目配置拆分
当集合数量较多时，可采用模块化配置结构：
typescript.ts
rust.ts
index.ts
…
typescript
rust
配置代码组织示例：
.vuepress/config.ts
import { defineUserConfig } from 'vuepress'
import { plumeTheme } from 'vuepress-theme-plume'
import collections from './collections/index.ts'
export default defineUserConfig({
theme: plumeTheme({
collections
}),
}).vuepress/collections/index.ts
import { defineCollections } from 'vuepress-theme-plume'
import rust from './rust'
import typescript from './typescript'
export default defineCollections([
rust,
typescript,
]).vuepress/collections/typescript.ts
import { defineCollection } from 'vuepress-theme-plume'
export default defineCollection({
type: 'doc',
dir: 'typescript',
link: '/typescript/',
title: 'TypeScript 文档',
sidebar: [
'guide/intro.md',
'guide/getting-start.md',
'config/config-file.md',
]
})侧边栏配置详解
文件结构示例
假设 TypeScript 文档包含以下结构：
intro.md
getting-start.md
config-file.md
configuration.md
basic.md
syntax.md
modules.md
Required.md
Omit.md
README.md
自动生成侧边栏
最简单的配置方式使用自动生成：
import { defineCollection } from 'vuepress-theme-plume'
export default defineCollection({
type: 'doc',
dir: 'typescript',
sidebar: 'auto' // 自动生成侧边栏
})主题根据目录结构自动配置侧边栏。
排序控制：通过数字前缀管理显示顺序
1.intro.md
2.getting-start.md
1.config-file.md
2.configuration.md
…
数字前缀仅用于排序，不会在侧边栏中显示。
自动折叠：默认情况下，侧边栏不会自动折叠，可以通过配置 sidebarCollapsed 开启自动折叠：
import { defineCollection } from 'vuepress-theme-plume'
export default defineCollection({
type: 'doc',
dir: 'typescript',
sidebar: 'auto',
sidebarCollapsed: true,
})sidebarCollapsed 有以下可选值：
undefined: 默认，不自动折叠true: 默认全部折叠false: 默认全部展开
自动生成次级侧边栏
为了更加灵活的控制侧边栏，减少配置的复杂度，主题允许配置仅自动生成次级侧边栏：
import { defineCollection } from 'vuepress-theme-plume'
export default defineCollection({
type: 'doc',
dir: 'typescript',
sidebar: [
// 次级 items 自动读取 typescript/guide 目录
{ text: '指南', prefix: 'guide', items: 'auto' },
// 次级 items 自动读取 typescript/config 目录
{ text: '配置', prefix: 'config', items: 'auto' },
],
})自定义侧边栏配置
基础配置类型
interface SidebarItem {
text?: string // 显示文本
link?: string // 链接地址
icon?: ThemeIcon // 图标配置
badge?: string | ThemeBadge // 徽章
prefix?: string // 链接前缀
items?: 'auto' | (string | SidebarItem)[] // 下一级侧边栏
collapsed?: boolean // 折叠状态
}配置示例
基础链接配置：
采用简写形式，可以传入 md 文件的路径或页面链接地址， 主题会自动读取文件的 frontmatter 配置作为侧边栏配置。
sidebar: [
// 绝对路径时，
// 在 themeConfig.sidebar 中是相对于 `key` 前缀的路径
// 在 collection 中是相对于 `dir` 的路径
'/guide/intro.md', // markdown 文件地址
'/guide/getting-start/', // 页面链接地址
'/config/config-file', // 可以省略 `.md` 后缀
]完整对象配置：
sidebar: [
{ text: '介绍', link: '/guide/intro' },
{ text: '快速上手', link: '/guide/getting-start' },
]嵌套分组配置：
sidebar: [
{
text: '指南',
prefix: '/guide',
items: [
{ text: '介绍', link: 'intro' },
'getting-start', // 简写形式
],
},
{
text: '配置',
prefix: '/config',
items: 'auto', // 自动生成该分组下的侧边栏
},
]Prefix 路径处理规则
prefix 用于简化相同前缀的链接配置：
const sidebarItem: SidebarItem = {
prefix: '/guide',
items: [
'intro', // → /guide/intro.md
'/config/config-file', // → /config/config-file.md (绝对路径)
{ link: '/blog/' }, // → /guide/blog/
{ link: '/config/' } // → /config.md (绝对路径)
]
}路径判断规则：
- 以
/开头：绝对路径，不拼接 prefix - 其他情况：相对路径，与 prefix 拼接
多级嵌套示例：
const sidebarItem: SidebarItem = {
prefix: '/guide',
items: [
'intro', // → /guide/intro.md
{
prefix: '/config', // 绝对路径，抛弃上级的 prefix
items: ['config-file'] // → /config/config-file.md
},
{
prefix: 'blog', // 相对路径，拼接上级的 prefix
items: ['intro'] // → /guide/blog/intro.md
}
]
}层级深度限制
避免超过 3 层嵌套的侧边栏配置，过深的层级会影响用户体验和界面美观。
视觉增强功能
图标配置
支持多种图标源，通过 markdown.icon.provide 配置：
sidebar: [
{
text: '指南',
prefix: '/guide',
icon: 'ep:guide', // Iconify 图标
items: [
{ text: '介绍', link: 'intro', icon: 'ph:info-light' },
],
},
]本地图标配置：
const sidebarItem: SidebarItem = {
text: '指南',
icon: '/images/guide.png', // 本地图片
items: [
{
text: '介绍',
icon: 'https://example.com/icon.png' // 远程图片
},
]
}本地资源路径
本地图片路径应从 / 开始，对应 .vuepress/public/ 目录：
guide.png
info.png
徽章功能 v1.0.0-rc.143 +
通过徽章提供额外信息提示：
sidebar: [
{
text: '指南',
badge: { text: '新', type: 'danger' }, // 对象形式
items: [
{ text: '介绍', badge: '推荐' }, // 字符串简写
],
},
]Frontmatter 配置：
---
title: 介绍
badge:
text: 新功能
type: danger
---分组分隔符
在复杂侧边栏中添加视觉分隔：
sidebar: [
{
text: '指南',
items: [
'项目 1',
'项目 2',
{ text: '高级功能', link: '---' }, // 分隔符
'项目 3',
'项目 4',
],
},
]分隔符特征：link 字段包含至少三个连续的 -
