vitepress-plugin-sidebar-permalink

vitepress-plugin-sidebar-permalink

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

用法

// .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 变量直接使用生成的配置

• 插件默认忽略目录

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

修改侧边栏样式

// .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<string, string>	undefined	直接提供重写规则（不从文件读取）
options	{ collapsed: boolean }	{ collapsed: true }	侧边栏配置选项
navLinks	array	undefined	导航栏配置
ignoreDirs	IgnoreDirs	见上文	忽略目录配置