背景
旧文档站新增主题时，很容易只改 sidebar。技术上页面能访问，构建也通过，但用户仍然会问“入口在哪”。这是典型的信息架构问题：页面存在不等于入口可见。
这次经验也解释了为什么新的 Codex 对话经验站不继续复用旧 VitePress 壳。培训文档站适合线性课程和参考资料，但精美博客/知识库门面需要更强的首页叙事、精选文章和主题地图。
这次解决了什么
新增主题要解决的是读者路径，而不只是路由：
- 侧边栏能在文档树里找到。
- 首页能让新主题作为主要入口出现。
- 顶部导航能覆盖高频访问路径。
- 构建产物能静态部署，且发布说明明确。
关键过程
先确认当前站点结构：VitePress 的文档入口、主题配置、首页自定义导航分别在不同文件里。只改其中一个，读者路径就会断。
然后把新主题放进 sidebar 排序，把首页卡片补上，把顶部导航或自定义导航组件同步更新。对于课程流入口，还要确认它是不是由手写数组维护，不能只把文件放进目录。
最后跑静态构建，并把部署产物和 Nginx fallback 写清楚。文档站是静态站，构建通过和入口可见是两个独立验收点。
踩坑
最大的坑是把“页面存在”当成“用户找得到”。sidebar 是已有读者深入阅读时的路径，首页和顶部导航才是新读者的发现路径。
另一个坑是把所有知识站都做成文档站。文档站适合手册，经验站更需要按案例、主题和最近更新组织内容。
最后方案
VitePress 站新增主题时，默认检查三处：sidebar、首页入口、顶部导航。新的 Codex 经验站则独立出来，用 Astro 做公开知识库，避免被旧培训站的信息架构限制。
以后怎么做
以后只要用户说“要显眼”“入口在哪”“像正常博客知识库”，就不要只改路由。先画读者路径，再确认首页、导航、主题页和搜索入口是否互相连上。