VitePress

Appearance

vitepress-plugin-sidebar-permalink ​

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

github地址 ​

vitepress-plugin-sidebar-permalink

这是一个适用于vitepress的 Vite 插件，vitepress启动时，插件会重写路由用permalink作为链接并生成侧边栏。

vitepress插件

安装 ​

sh
npm install vitepress-plugin-sidebar-permalink -D
sh
yarn add vitepress-plugin-sidebar-permalink -D
sh
pnpm i vitepress-plugin-sidebar-permalink -D

用法 ​

配置 ​

ts
import { defineConfig } from 'vitepress'
import SidebarPermalinkPlugin, { generatedSidebar, generatedRewrites } from 'vitepress-plugin-sidebar-permalink'
// import rewritesJson from '../rewrites.json'

export default defineConfig({
  vite: {
    plugins: [
      SidebarPermalinkPlugin({
        root: 'docs',  //根目录
        dir: 'docs/articles', //Markdown文章目录路径
        rewritesPath: 'docs/rewrites.json',  //重写规则文件路径
     //   rewrites: rewritesJson.rewrites,  //直接提供的重写规则，启动时注释这个，生成json后再写，后续优先使用这个本地的json
        options: { collapsed: true },  //侧边栏是否折叠
        ignoreDirs: {               //忽略目录
          rewriteIgnores: [], 
          sidebarIgnores: [] 
        },
        navLinks: [  //导航栏
          { text: '组件', link: '/pages/fe4521' },
          { text: '后端', link: '/pages/571de5' },
          { text: '资源', link: '/pages/87a36a' }
        ],
      })
    ]
  },
  // 使用插件自动生成的侧边栏和重写规则
  rewrites: generatedRewrites, 
  themeConfig: {
    sidebar: generatedSidebar
  }
})
ts
export interface SidebarPermalinkOptions {
    /**
     * 根目录, 默认为 'docs'
     */
    root?: string; 
    /**
     * Markdown文章目录路径，默认为 'docs/articles'
     */
    dir?: string; 
    /**
     * 重写规则文件路径，默认为 'docs/rewrites.json'
     */
    rewritesPath?: string; 
    /**
     * 直接提供的重写规则，一般为rewritesJson.rewrites，rewritesJson为生成的json文件
     *
     */
    rewrites?: Record<string, string>, 
   /**
    * sidebar配置，是否折叠
    */
    options?: { collapsed: boolean }, 
    /**
     * 导航栏
     */
    navLinks?: { text: string, link?: string, items?: any[] }[] | null | undefined,   
     /**
     * 忽略的侧边栏目录列表
     *
     * */
    ignoreDirs?: IgnoreDirs; 
}


export interface IgnoreDirs {
  /**
   * 重写规则默认忽略目录为 [".vitepress", "node_modules", "public", "dist"]    
   */
  rewriteIgnores: string[];
   /**
   * 侧边栏默认忽略目录为 [".vitepress", "node_modules", "public", "dist", "@pages", "index.md"]    
   */
  sidebarIgnores: string[];
}

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

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

  • 插件默认忽略目录

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

修改侧边栏样式 ​

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

配置选项 ​

选项类型默认值说明
rootstring'docs'根目录路径
dirstring'docs/articles'md文件所在目录
rewritesPathstring'docs/rewrites.json'重写规则文件路径
rewritesRecord<string, string>undefined直接提供重写规则（不从文件读取）
options侧边栏配置选项
navLinksarrayundefined导航栏配置
ignoreDirsIgnoreDirs见上文忽略目录配置