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