侧边栏
约 1657 字大约 6 分钟
指南快速开始
2025-09-29
概述
侧边栏是文档常见的页面导航方式,可以快速定位到文档内容。
主题提供了两种方式配置侧边栏,包括:
- 通过主题配置的
sidebar
选项配置侧边栏 - 在 类型为
doc
的集合 中配置侧边栏
文件结构与基础配置
目录结构设计
典型的项目结构可能如下:
docs
typescript# TypeScript 学习笔记
basic.md
types.md
rust# Rust 编程笔记
tuple.md
struct.md
README.md# 站点首页
通过sidebar
配置
这种方式适用于简单小巧的文档站点。
import { defineUserConfig } from 'vuepress'
import { plumeTheme } from 'vuepress-theme-plume'
export default defineUserConfig({
theme: plumeTheme({
sidebar: {
'/typescript/': [
'basic',
'types'
],
'/rust/': [
'tuple',
'struct'
]
}
})
})
import { defineThemeConfig } from 'vuepress-theme-plume'
export default defineThemeConfig({
sidebar: {
'/typescript/': [
'basic',
'types'
],
'/rust/': [
'tuple',
'struct'
]
}
})
通过 collection
配置 推荐
collections
(集合)可以灵活的组织和管理站点中的不同类别的文档,这种方式适用于复杂的站点。
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'],
}
],
})
})
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'],
}
],
})
配置时机建议
在创建文档文件前完成笔记配置。主题的 auto-frontmatter 功能会根据配置自动生成永久链接和侧边栏结构。
进阶配置管理
模块化配置方案
对于复杂项目,推荐使用主题提供的类型安全配置工具:
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
])
import { defineUserConfig } from 'vuepress'
import { plumeTheme } from 'vuepress-theme-plume'
import collections from './collections'
export default defineUserConfig({
theme: plumeTheme({
collections
}),
})
大型项目配置拆分
当集合数量较多时,可采用模块化配置结构:
docs
.vuepress
collections
typescript.ts
rust.ts
index.ts
…
typescript
…
rust
…
配置代码组织示例:
import { defineUserConfig } from 'vuepress'
import { plumeTheme } from 'vuepress-theme-plume'
import collections from './collections/index.ts'
export default defineUserConfig({
theme: plumeTheme({
collections
}),
})
import { defineCollections } from 'vuepress-theme-plume'
import rust from './rust'
import typescript from './typescript'
export default defineCollections([
rust,
typescript,
])
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 笔记 包含以下结构:
docs
typescript
guide
intro.md
getting-start.md
config
config-file.md
configuration.md
reference
basic.md
syntax.md
modules.md
built-in
types
Required.md
Omit.md
README.md
自动生成侧边栏
最简单的配置方式使用自动生成:
import { defineCollection } from 'vuepress-theme-plume'
export default defineCollection({
type: 'doc',
dir: 'typescript',
sidebar: 'auto' // 自动生成侧边栏
})
主题根据目录结构自动配置侧边栏。
排序控制:通过数字前缀管理显示顺序
typescript
1.guide
1.intro.md
2.getting-start.md
2.config
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/
目录:
docs
.vuepress
public
images
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
字段包含至少三个连续的 -