知识库维护工作流：让文档、README 与侧边栏自动同步

归类：开发工具 / 知识库维护 / VitePress 发生时间：2026-03-24 状态：✅ 已落地

---

一、问题现象 / 背景

知识库类仓库很容易遇到一个典型问题：正文文章已经新增或更新了，但 README、分类索引页和站点侧边栏仍然依赖手工维护，久而久之就会出现目录和实际文档不一致、搜索得到文章但导航找不到入口、维护成本越来越高的情况。

当知识沉淀依赖 AI 或脚本自动写文档时，这类漂移会更明显，因为正文新增速度通常快于“补目录、补索引、补导航”的人工动作。

二、排查过程

1. 先确定什么才是事实来源

真正需要人工维护的，不应该是多个展示层文件，而应该只有两类源信息：

1. 公开文章本身，例如 site/<category>/<slug>.md
2. 分类注册表，例如分类标题、排序和分类说明

只要这两类源稳定，README、分类索引页和 VitePress sidebar 都可以由脚本生成。

2. 找出最容易漂移的环节

手工维护时，通常最容易漏掉的是：

• site/README.md 中的文档列表
• site/<category>/index.md 中的分类入口页
• .vitepress/config.mts 中的 sidebar 链接

这三个文件都属于“展示层索引”，并不适合作为额外事实来源。

三、根本原因 / 设计思路

根本原因不是“维护人忘记更新 README”，而是“同一份知识被拆成了多个需要人工同步的地方”。

更稳妥的做法是：

1. 给每篇公开文章补上结构化 frontmatter，例如 title、summary、date、category
2. 用一个同步脚本扫描 site/ 目录
3. 基于文章元信息和分类注册表生成：
   • site/README.md
   • site/<category>/index.md
   • .vitepress/config.mts
4. 把 npm run site:sync 接入构建或发布流程，作为最终兜底

这样一来，文章正文才是长期维护对象，而索引文件只保留生成结果。

四、解决方案 / 推荐做法

推荐目录分工

site/<category>/<slug>.md          # 公开文章源文件
scripts/sync-site-indexes.mjs      # 索引和 sidebar 生成逻辑
site/README.md                     # 自动生成
site/<category>/index.md           # 自动生成
.vitepress/config.mts              # 自动生成

推荐 frontmatter

---
title: "知识库维护工作流：让文档、README 与侧边栏自动同步"
summary: "一句话说明这篇文章解决什么问题。"
date: "2026-03-24"
category: "tools"
status: "published"
---

推荐命令

# 公开文章更新后，先同步索引
npm run site:sync

# 再执行构建校验
npm run docs:build

# 需要对外发布时执行
npm run publish -- "docs: sync knowledge base indexes"

五、快捷实用介绍

如果你正在维护一个持续增长的知识库仓库，最省心的实践是：

1. 新增文章时只写正文和 frontmatter
2. 不再手工编辑 README、分类页和 sidebar
3. 统一通过同步脚本刷新索引
4. 把同步命令接到构建或发布脚本里做兜底

这套做法的收益是：

• 索引不会和正文长期漂移
• skill / AI 自动沉淀时更稳定
• 新增分类或批量补文档时维护成本更低

六、预防建议

1. 不要把展示层文件当成额外事实来源。
2. 尽量让 frontmatter 保持完整，尤其是 summary 和 category。
3. 当分类结构调整时，优先改同步脚本或分类注册表，而不是手工批量改多个索引文件。
4. 把“同步索引”写进技能或发布流程，否则长期仍会回到人工补目录的旧习惯。