doc 集合
约 992 字大约 3 分钟
2025-10-05
概述
doc 集合专为管理结构化文档而设计,适用于文章间存在强关联关系、需要整体呈现的场景。典型应用包括:
- API 技术文档
- 产品使用教程
- 专题开发指南
- 知识体系笔记
该集合通过智能侧边导航栏实现文档间的快速跳转与内容组织。
主题支持配置多个独立的 doc 集合
创建 doc 集合
通过三个步骤快速创建文档集合:
创建文档目录
docs
guide
intro.md
install.md
…
配置集合参数
.vuepress/config.tsimport {
defineUserConfig} from 'vuepress' import {plumeTheme} from 'vuepress-theme-plume' export defaultdefineUserConfig({theme:plumeTheme({collections: [ {type: 'doc',dir: 'guide',title: '指南' } ] }) }).vuepress/plume.config.tsimport {
defineThemeConfig} from 'vuepress-theme-plume' export defaultdefineThemeConfig({collections: [ {type: 'doc',dir: 'guide',title: '指南' } ] })完成配置
多语言支持
为不同语言版本配置独立的文档集合:
docs
guide
intro.md
install.md
…
en
guide
intro.md
install.md
…
.vuepress/config.ts
import { defineUserConfig } from 'vuepress'
import { plumeTheme } from 'vuepress-theme-plume'
export default defineUserConfig({
theme: plumeTheme({
locales: {
'/': {
collections: [
{ type: 'doc', dir: 'guide', title: '指南' }
]
},
'/en/': {
collections: [
{ type: 'doc', dir: 'guide', title: 'Guide' }
]
}
}
})
})
.vuepress/plume.config.ts
import { defineThemeConfig } from 'vuepress-theme-plume'
export default defineThemeConfig({
locales: {
'/': {
collections: [
{ type: 'doc', dir: 'guide', title: '指南' }
]
},
'/en/': {
collections: [
{ type: 'doc', dir: 'guide', title: 'Guide' }
]
}
}
})
目录结构配置
dir
参数定义文档源文件位置,支持相对和绝对路径:
dir: 'guide' // 指向 docs/guide
dir: '/guide/' // 等效写法
dir: './guide/' // 等效写法
dir: '/team/guide/' // 指向 docs/team/guide
多语言环境下路径相对于对应的语言目录
自动 Frontmatter 生成
仅在执行 vuepress dev
或 vuepress build
后生效
支持自动生成文档元数据,可自定义处理逻辑:
.vuepress/config.ts
import { defineUserConfig } from 'vuepress'
import { plumeTheme } from 'vuepress-theme-plume'
export default defineUserConfig({
theme: plumeTheme({
collections: [
{
type: 'doc',
dir: 'guide',
title: '指南',
autoFrontmatter: {
title: true, // 自动生成标题
createTime: true, // 自动生成创建时间
permalink: true, // 自动生成永久链接
transform: (data, context, locale) => { // 自定义转换
data.foo ??= 'foo'
return data
}
}
}
]
})
})
.vuepress/plume.config.ts
import { defineThemeConfig } from 'vuepress-theme-plume'
export default defineThemeConfig({
collections: [
{
type: 'doc',
dir: 'guide',
title: '指南',
autoFrontmatter: {
title: true, // 自动生成标题
createTime: true, // 自动生成创建时间
permalink: true, // 自动生成永久链接
transform: (data, context, locale) => { // 自定义转换
data.foo ??= 'foo'
return data
}
}
}
]
})
生成效果:
docs/guide/install.md
---
title: install
createTime: 2025/03/24 20:15:12
permalink: /guide/a1b2c3d4/
---
侧边栏配置
提供灵活的侧边栏导航配置选项:
.vuepress/config.ts
import { defineUserConfig } from 'vuepress'
import { plumeTheme } from 'vuepress-theme-plume'
export default defineUserConfig({
theme: plumeTheme({
collections: [
{
type: 'doc',
dir: 'guide',
title: '指南',
sidebar: [ // 手动配置导航项
'intro',
'install',
],
sidebarScrollbar: true, // 显示侧边栏滚动条
}
]
})
})
.vuepress/plume.config.ts
import { defineThemeConfig } from 'vuepress-theme-plume'
export default defineThemeConfig({
collections: [
{
type: 'doc',
dir: 'guide',
title: '指南',
sidebar: [ // 手动配置导航项
'intro',
'install',
],
sidebarScrollbar: true, // 显示侧边栏滚动条
}
]
})
自动生成侧边栏
设置 sidebar: 'auto'
自动基于目录结构生成导航:
.vuepress/config.ts
import { defineUserConfig } from 'vuepress'
import { plumeTheme } from 'vuepress-theme-plume'
export default defineUserConfig({
theme: plumeTheme({
collections: [
{
type: 'doc',
dir: 'guide',
title: '指南',
sidebar: 'auto', // 自动生成导航结构
sidebarCollapsed: undefined, // 折叠状态:true-折叠 false-展开
}
]
})
})
.vuepress/plume.config.ts
import { defineThemeConfig } from 'vuepress-theme-plume'
export default defineThemeConfig({
collections: [
{
type: 'doc',
dir: 'guide',
title: '指南',
sidebar: 'auto', // 自动生成导航结构
sidebarCollapsed: undefined, // 折叠状态:true-折叠 false-展开
}
]
})
手动配置侧边栏
集合首页定制
目录下的 README.md
自动作为集合首页,支持转换为功能丰富的门户布局:
typescript/README.md
---
pageLayout: home
config:
- type: hero
title: TypeScript 完全指南
description: 从基础到进阶的 TypeScript 学习路径
- type: features
features:
- title: 类型系统
details: 深入理解 TypeScript 类型系统
icon: mdi:code-braces
- title: 高级特性
details: 掌握泛型、装饰器等高级功能
icon: mdi:rocket-launch
---