VitePress 搭建与实施

需求：将整理好的知识库 (knowledge/ 目录) 以美观、便捷的方式展示出来，支持个人查阅和对外分享。

一、 技术选型

选择 VitePress 作为静态站点生成器。

• 优势：极速性能 (Vite)、Vue 驱动、Markdown 中心、默认主题精美。
• 对比：比 Docusaurus 更轻量，比 GitBook 更自由且免费。

二、 实施架构

full-stack/
├── .vitepress/         <-- [配置] VitePress 的配置目录
│   ├── config.mjs      <-- 站点配置 (导航栏、侧边栏)
│   └── theme/          <-- 自定义主题
├── knowledge/          <-- [数据源] 文档内容
├── package.json        <-- 依赖管理
└── index.md            <-- 站点首页

三、 关键配置策略

3.1 目录结构配置

保持 knowledge 目录不动，在根目录配置 VitePress，通过 Sidebar 配置指向 knowledge 中的文件。

3.2 导航与索引 (Navigation & Indexing)

为了解决 VitePress 404 问题并提供良好的导航体验：

1. Index.md: 每个目录下必须包含 index.md。
2. 自动化脚本: 使用 knowledge_gardener.py 或 generate_indexes.py 自动生成包含子目录/文件列表的 index.md。

3.3 汉化与标准化

1. Front Matter: 所有文档必须包含标准 Front Matter (title, order)。
2. 目录映射: 使用脚本将英文目录名映射为中文标题 (如 architecture -> 架构设计) 显示在侧边栏。

四、 部署方案

4.1 静态部署 (推荐)

• GitHub Pages: 利用 GitHub Actions 自动构建。
• Vercel: 一键部署，全球 CDN 加速。

4.2 本地开发

运行 npm run docs:dev (即 vitepress dev)，在 http://localhost:5173 实时预览。

五、 维护计划

5.1 自动化维护

• 目录重命名: 使用 normalize_names.py 保持 kebab-case 英文命名。
• 索引更新: 定期运行 knowledge_gardener.py 更新目录索引。

5.2 归档策略

• _archive 目录存放历史归档，不纳入主导航。
• 定期清理闲置目录 (community, journal 等)。