vitepress-plugin-sidebar-permalink

VitePress 插件：自动生成 sidebar 侧边栏和 permalink rewrites 映射，支持数字前缀排序、collapsed 配置、permalink 匹配高亮、目录/文件名美化等。

用法

``ts
// .vitepress/config.ts
import { defineConfig } from 'vitepress'
import SidebarPermalinkPlugin, { generatedSidebar, generatedRewrites } from 'vitepress-plugin-sidebar-permalink'

export default defineConfig({
vite: {
plugins: [
SidebarPermalinkPlugin({
root: 'docs', // 根目录，默认为 'docs'
dir: 'docs/articles', // md文件所在目录，默认为 'docs/articles'
rewritesPath: 'docs/rewrites.json', // 重写规则文件路径，默认为
'docs/rewrites.json'
rewrites: {}, // 直接提供重写规则，一般为rewritesJson.rewrites
options: { collapsed: true }, // 侧边栏是否折叠，默认为 true
ignoreDirs: {
rewriteIgnores: [], // 默认重写规则忽略目录
sidebarIgnores: [] // 默认侧边栏忽略目录
},
navLinks: [ // 可选，导航栏配置
{ text: '组件', link: '/pages/fe4521' },
{ text: '后端', link: '/pages/571de5' },
{ text: '资源', link: '/pages/87a36a' }
],
})
]
},
// 使用插件自动生成的侧边栏和重写规则
rewrites: generatedRewrites,
themeConfig: {
sidebar: generatedSidebar
}
})
`

- 插件会在启动时生成侧边栏和重写规则，优先从rewrites参数获取重写规则，其次从生成的json文件读取，建议生成json文件后配置该参数

- 通过导出的 generatedSidebar 和 generatedRewrites 变量直接使用生成的配置

- 插件默认忽略目录

`ts
{
// 默认重写规则忽略目录
rewriteIgnores: ['.vitepress', 'node_modules', 'public', 'dist'],
// 默认侧边栏忽略目录
sidebarIgnores: ['.vitepress', 'node_modules', 'public', 'dist', '@pages', 'index.md']
}
`

$3

`ts
// .vitepress/theme/index.ts
import type { Theme } from 'vitepress'
import DefaultTheme from 'vitepress/theme'
import 'vitepress-plugin-sidebar-permalink/index.css'

export default {
extends: DefaultTheme,
enhanceApp({ router }) {
// 自定义增强逻辑
}
} satisfies Theme
`

特性

- 全自动生成：插件启动时自动生成侧边栏和重写规则，无需手动调用
- 自动生成侧边栏：支持数字前缀排序、collapsed 配置、permalink 匹配高亮、目录/文件名美化
- 自动生成重写规则：支持 permalink 映射，方便管理文档 URL
- 支持私有页面：通过 frontmatter 中的 private: true 标记私有页面（只适配本站主题包，配置后即可开启加密，访问需登录，单独使用无效）
- 支持隐藏侧边栏项：通过 frontmatter 中的 sidebar: false 可以在侧边栏中隐藏特定页面
- 灵活配置：可自定义忽略目录、折叠状态、导航链接等
- 保持与 VitePress 官方 sidebar 配置行为一致
- 支持直接导出配置：通过 generatedSidebar 和 generatedRewrites 直接使用生成的配置

配置选项

| 选项 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| root | string | 'docs' | 根目录路径 |
| dir | string | 'docs/articles' | md文件所在目录 |
| rewritesPath | string | 'docs/rewrites.json' | 重写规则文件路径 |
| rewrites | Record | undefined | 直接提供重写规则（不从文件读取） |
| options | { collapsed: boolean } | { collapsed: true } | 侧边栏配置选项 |
| navLinks | array | undefined | 导航栏配置 |
| ignoreDirs` | IgnoreDirs | 见上文 | 忽略目录配置 |