个人 Wiki（VitePress）搭建与约定

背景与目标

我需要一个“公开版第二大脑”：

• 自己查资料要快（速查/踩坑）
• 对外分享链接要稳定（URL 不频繁变）
• 维护成本要低（写 Markdown 即可）

约束

• 只用 VitePress 默认能力（尽量不加依赖、不写复杂主题）
• 顶层路由稳定（后期不大规模移动）
• 内容优先：先写起来再优化结构

技术选型与取舍

选择 VitePress 的原因：

• Markdown 写作体验好
• 站点结构简单：文件路径即路由
• 构建产物是静态站，部署极轻

取舍：

• 不追求复杂动态功能（评论/搜索可以后续再加）
• 先靠目录结构 + sidebar 导航解决“可找性”

信息架构（路由）

当前顶层分区：

• /debug/：技术踩坑（问题驱动）
• /notes/：主题型速查
• /ai/：AI 实践与资产
• /projects/：项目文档/复盘
• /growth/：周报/成长记录

更详细的约定见仓库根目录：路由规范.md。

目录结构（当前）

wiki/
  docs/
    .vitepress/config.mts
    index.md
    debug/
    notes/
    ai/
    projects/
    growth/

开发与部署

本地开发

npm run docs:dev

构建

npm run docs:build

构建产物在：docs/.vitepress/dist/（不要提交进 git）。

反代/HMR（开发时）

如果把 vitepress dev 放在内网，通过 Nginx 反代到外网域名，需要注意 WebSocket：

• 反代要支持 Upgrade / Connection
• 否则 HMR 可能不工作

踩坑记录见：

• /debug/vitepress-hmr-behind-nginx

写作流程（我自己的）

1. 遇到真实问题 → 先写进 /debug/
2. 形成可复用的结论/片段 → 抽到 /notes/
3. 项目阶段性成果 → /projects/
4. 每周总结 → /growth/weekly/

模板（内部）统一在根目录：示例与模板.md。