【VitePress】新增md文件后自动更新侧边栏导航

说在前面

• 操作系统：windows11
• node版本：v18.19.0
• npm版本：10.2.3
• vitepress版本：1.6.3
• 完整代码：github

先看效果

• 模板用的就是官方主题
  
  

代码结构

详细说明

侧边栏格式

• 通常，侧边栏定义在config.mts中

  export default {themeConfig: {sidebar: [{text: 'Guide',items: [{ text: 'Introduction', link: '/introduction' },{ text: 'Getting Started', link: '/getting-started' },...]}]}
  }
  

  例如上述代码定义了这样子的侧边栏：
  
• 而现在，我们需要根据目录内容，自动生成一个侧边栏

utils

• 在该目录下，我们实现了一个脚本，用于自动生成侧边栏内容

  import FastGlob from 'fast-glob';
  const { glob } = FastGlob
  import fs from 'fs/promises';
  import path from 'path';
  import type { DefaultTheme } from 'vitepress';
  import chokidar from 'chokidar';type SidebarConfig = Record<string, DefaultTheme.SidebarItem[]>;export async function generateAutoSidebar(): Promise<SidebarConfig> {const basePath = path.join(process.cwd(), 'doc/reviews');const branches = await glob('*/', {cwd: basePath,onlyDirectories: true,deep: 1});const sidebar: DefaultTheme.SidebarItem[] = [];for (const branchDir of branches) {const branchName = branchDir.replace(/\/$/, '');const mdFiles = await glob(`${branchDir}/*.md`, {cwd: basePath,ignore: ['**/_*.md']});const items: DefaultTheme.SidebarItem[] = mdFiles.map(file => {const fileName = path.basename(file, '.md');return {text: `${fileName}.md`,link: `/reviews/${branchDir}/${fileName}`};}).sort((a, b) => {const numA = parseInt(a.text.match(/\d+/)?.[0] || '0');const numB = parseInt(b.text.match(/\d+/)?.[0] || '0');return numA - numB;});sidebar.push({text: branchName,collapsed: false,items});}return { '/reviews/': sidebar };
  }export async function writeSidebarConfig(): Promise<void> {const sidebarConfig = await generateAutoSidebar();const configContent = `// Auto-generated sidebar config
  import type { DefaultTheme } from 'vitepress';export const sidebarConfig: DefaultTheme.Config['sidebar'] = ${JSON.stringify(sidebarConfig, null, 2)};
  `;var p = path.join(process.cwd(), 'doc/.vitepress/sidebar.generated.ts')await fs.writeFile(p,configContent);
  }writeSidebarConfig()
  

• 通过执行tsx doc/.vitepress/utils/generateSidebar.ts --watch，将在./doc/.vitepress/目录下自动生成sidebar.generate.ts文件，以上述reviews文件夹中内容为例，生成的内容为：

  // Auto-generated sidebar config
  import type { DefaultTheme } from 'vitepress';export const sidebarConfig: DefaultTheme.Config['sidebar'] = {"/reviews/": [{"text": "aaa","collapsed": false,"items": [{"text": "1.md","link": "/reviews/aaa/1"},{"text": "2.md","link": "/reviews/aaa/2"}]},{"text": "bbb","collapsed": false,"items": [{"text": "1.md","link": "/reviews/bbb/1"}]}]
  };
  

• 而后，在我们的config.mts中引用即可

  import { defineConfig } from 'vitepress'
  import { sidebarConfig } from './sidebar.generated.js';// https://vitepress.dev/reference/site-config
  export default defineConfig({title: "coding",description: "code review helper",themeConfig: {// https://vitepress.dev/reference/default-theme-confignav: [{ text: 'Home', link: '/' },{ text: 'Reviews', link: '/reviews' }],sidebar: sidebarConfig,},async buildEnd() {const { writeSidebarConfig } = await import('./utils/generateSidebar.js');await writeSidebarConfig();}
  })
  

监听文件变化

• 在utils/generateSidebar.ts最后添加这一段，监控该目录下的文件变化，当有变化时，会自动调用writeSidebarConfig重新生成侧边栏内容

  // 开发模式文件监听
  if (process.env.NODE_ENV === 'development' || process.argv.includes('--watch')) {const watcher = chokidar.watch('doc/reviews/**/*.md', {ignored: /(^|[/\\])\../,persistent: true});watcher.on('add', () => writeSidebarConfig()).on('unlink', () => writeSidebarConfig());process.stdin.resume();
  }
  

使用pm2管理监听进程

• 建议在linux下使用，windows下有问题
• 安装

  npm install -D pm2
  

• 新建ecosystem.config.js

  module.exports = {apps: [{name: 'vitepress',script: 'npm',args: 'run docs:dev',watch: ['doc/.vitepress/sidebar.generated.ts']},{name: 'sidebar-watcher',script: 'npm',args: 'run dev:sidebar',watch: false}]
  };
  

• 修改package.json

  {"scripts": {"start": "pm2 start eco.config.js","stop": "pm2 stop eco.config.js","docs:dev": "vitepress dev doc","docs:build": "vitepress build doc","docs:preview": "vitepress preview doc","docs:sidebar": "tsx doc/.vitepress/utils/generateSidebar.ts --watch"},"devDependencies": {// ...}
  }
  

• 运行

  npm run start