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 | 见上文 | 忽略目录配置 |