vitepress-plugin-sidebar-url

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

github地址

vitepress-plugin-sidebar-url vitepress-plugin-sidebar-url
vitepress插件

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

安装 

      npm install vitepress-plugin-sidebar-url -D
    
      yarn add vitepress-plugin-sidebar-url -D
    
      pnpm i vitepress-plugin-sidebar-url -D

用法

配置 

      import { defineConfig } from 'vitepress'
import SidebarurlPlugin, { generatedSidebar, generatedRewrites } from 'vitepress-plugin-sidebar-url'
// import rewritesJson from '../rewrites.json'

export default defineConfig({
  vite: {
    plugins: [
      SidebarurlPlugin({
        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
  }
})
    
      export interface SidebarurlOptions {
    /**
     * 根目录, 默认为 '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 变量直接使用生成的配置

  • 插件默认忽略目录

          {
  // 默认重写规则忽略目录
  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-url/index.css'

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

特性

  • 全自动生成：插件启动时自动生成侧边栏和重写规则，无需手动调用
  • 自动生成侧边栏：支持数字前缀排序、collapsed 配置、url 匹配高亮、目录/文件名美化
  • 自动生成重写规则：支持 url 映射，方便管理文档 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 见上文 忽略目录配置

声明

作者： liyao

版权：本博客所有文章除特别声明外，均采用CCBY-NC-SA4.O许可协议。转载请注明!

链接： https://vp.xiaoying.org.cn/pages/47a27c/

最后更新于 2025-10-02 15:53 history