自动生成侧边栏
这个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
)。
脚本使用说明
准备工作:
在VitePress项目的根目录下新建
generate-sidebar.js
并写入以下代码javascriptconst 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));
运行脚本:
终端或命令行界面。
切换到VitePress项目的根目录。
运行脚本
bashnode generate-sidebar.js
脚本会读取
docs
目录下的文件和目录结构,然后在docs
目录下生成或更新sidebar.json
文件。
在VitePress配置中引用生成的
sidebar.json
:- 修改您的VitePress配置文件(
./docs/vitepress/config.mts
),引入并使用sidebar.json
作为侧边栏配置。 - 示例代码:typescript
import { defineConfig } from 'vitepress' import sidebarConfig from '../sidebar.json' // 其他配置... sidebar: sidebarConfig, // 使用导入的侧边栏配置
- 修改您的VitePress配置文件(
注意事项:
- 每次文档结构变化后,都需要重新运行此脚本以更新侧边栏配置。
- 确保在VitePress项目构建或本地预览前更新
sidebar.json
文件。
通过遵循上述步骤,您可以轻松维护和更新VitePress项目的侧边栏配置,确保文档结构的变化能够快速反映在最终生成的站点中。