vitepress-plugin-sidebar-permalink/README.md

VitePress 自动生成 sidebar 和 permalink rewrites 的插件

# 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']
  }
  ```

  

### 修改侧边栏样式

```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` 标记私有页面（只适配[本站主题包](https://vp.xiaoying.org.cn/pages/9d746f)，配置后即可开启加密，访问需登录，`单独使用无效`）
- **支持隐藏侧边栏项**：通过 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 | 见上文 | 忽略目录配置 |