Skip to content

自动生成侧边栏

这个Node.js脚本旨在为VitePress项目自动生成侧边栏(sidebar)配置,以简化文档维护工作。它会递归遍历指定的文档目录,自动识别Markdown文件和目录结构,然后生成相应的侧边栏配置对象,并保存为一个JSON文件。

适用于文档内容频繁更新的项目,可以显著减少手动编辑配置文件的需要。

实现功能

  • 自动遍历文档目录:脚本会递归地遍历docs目录下的所有文件和子目录。
  • 生成侧边栏配置:为每个找到的Markdown文件和子目录生成侧边栏配置项。
  • 过滤规则:自动过滤隐藏文件(以.开头的文件)和指定的./docs/index.md文件,防止它们出现在侧边栏中。
  • JSON输出:将生成的侧边栏配置保存为./docs/sidebar.json文件,以便在./docs/vitepress/config.mts配置中引用。

需要满足的目录结构

  • 文档目录应位于VitePress项目根目录下的docs文件夹内。
  • docs目录可以包含任意数量的Markdown文件和子目录。
  • 子目录可以包含更多Markdown文件或进一步嵌套的子目录。
  • 项目根目录应包含此脚本文件(例如,命名为generate-sidebar.js)。

脚本使用说明

  1. 准备工作

    在VitePress项目的根目录下新建generate-sidebar.js并写入以下代码

    javascript
    const fs = require('fs');
    const path = require('path');
    
    const docsPath = path.resolve(__dirname, './docs'); // 确保路径正确
    
    function generateSidebarConfig(dirPath, basePath = '') {
      const entries = fs.readdirSync(dirPath, { withFileTypes: true });
    
      const sidebar = entries
        // 过滤掉以 . 开头的文件(通常是隐藏文件)和指定的 ./docs/index.md 文件
        .filter(entry => {
          const fullPath = path.join(dirPath, entry.name);
          // 检查是否是 ./docs/index.md 文件
          const isDocsIndexMd = fullPath.replace(/\\/g, '/') === path.join(docsPath, 'index.md').replace(/\\/g, '/');
          return !entry.name.startsWith('.') && !isDocsIndexMd;
        })
    
        .map(entry => {
          const entryPath = path.join(dirPath, entry.name);
          // 为 relativePath 的构建逻辑添加一个前导 '/'
          const relativePath = '/' + path.join(basePath, entry.name.replace(/\.md$/, '')).replace(/\\/g, '/');
    
    
          if (entry.isDirectory()) {
            // 如果是目录,递归构建其下的sidebar配置
            const nestedConfig = generateSidebarConfig(entryPath, `${relativePath}/`);
            return { text: entry.name, items: nestedConfig };
          } else if (entry.isFile() && entry.name.endsWith('.md')) {
            // 如果是Markdown文件,添加到sidebar配置中
            const basename = path.basename(entry.name, '.md');
            const link = `${basePath}${basename === 'index' ? '' : basename}`;
            return { text: basename, link: link.replace(/\\/g, '/') }; // 确保链接路径是正斜杠
          }
        })
        .filter(Boolean); // 过滤掉undefined项
    
      return sidebar;
    }
    
    const sidebarConfig = generateSidebarConfig(docsPath);
    
    const sidebarPath = path.resolve(__dirname, './docs/sidebar.json');
    fs.writeFileSync(sidebarPath, JSON.stringify(sidebarConfig, null, 2));
  2. 运行脚本

    • 终端或命令行界面。

    • 切换到VitePress项目的根目录。

    • 运行脚本

      bash
      node generate-sidebar.js
    • 脚本会读取docs目录下的文件和目录结构,然后在docs目录下生成或更新sidebar.json文件。

  3. 在VitePress配置中引用生成的sidebar.json

    • 修改您的VitePress配置文件(./docs/vitepress/config.mts),引入并使用sidebar.json作为侧边栏配置。
    • 示例代码:
      typescript
      import { defineConfig } from 'vitepress'
      import sidebarConfig from '../sidebar.json'
        // 其他配置...
      
          sidebar: sidebarConfig, // 使用导入的侧边栏配置
  4. 注意事项

    • 每次文档结构变化后,都需要重新运行此脚本以更新侧边栏配置。
    • 确保在VitePress项目构建或本地预览前更新sidebar.json文件。

通过遵循上述步骤,您可以轻松维护和更新VitePress项目的侧边栏配置,确保文档结构的变化能够快速反映在最终生成的站点中。

Released under the MIT License.