开发记录：VitePress 首页表达与重点阅读路径增强

背景

M3 完成后，站点已经具备了搜索、SEO 和发布能力，但首页和总览页仍然偏“索引型”：

• 能找到入口
• 能查看专题
• 能正常搜索

但对于第一次进入站点的读者来说，还缺少几层关键指引：

• 这里最值得先看什么
• 最近哪里发生了更新
• 某个主题应该怎么按顺序阅读

因此 M4 的重点，是把站点继续从“能索引”推进到“更会引导阅读”。

本轮改动

1. 首页改成更完整的知识站入口

首页现在新增了下面几类信息：

• 站点统计卡片
• 重点模块卡片
• 重点专题卡片
• 最近更新卡片
• 建议阅读路径

这样首页不再只是 Hero + 几段列表，而开始具备“带人进入知识库”的能力。

2. 生成脚本开始采集原始 Markdown 的修改时间

这一轮专门增加了原始文件递归采集逻辑，直接从仓库中的 Markdown 文件读取：

• 标题
• 顶层模块名
• 最近修改时间

然后再生成“最近更新”视图。这样拿到的是内容真实更新时间，而不是 docs-site 生成时间。

3. 引入 3 个轻量主题组件

为了不把站点改造成高耦合手工页面，这轮只增加了 3 个展示型组件：

• SiteStatGrid.vue
• SiteDataGrid.vue
• SiteReadingPaths.vue

这几个组件都不自己取数，只负责接收生成脚本写入的 props 并展示。数据源仍然集中在生成脚本里。

4. 模块页和专题页也开始具备“推荐阅读感”

本轮不仅增强了首页，也同步增强了：

• 模块页推荐入口卡片
• 模块页最近更新区
• 专题页覆盖模块卡片
• 专题页推荐阅读卡片
• 专题页建议阅读路径

这样从首页进入某个模块或专题后，阅读体验能继续保持一致。

关键实现点

组件只做展示，不做数据计算

这一点很重要。VitePress 里如果让组件自己去查数据，维护复杂度会快速上升。

这轮坚持让所有数据在 scripts/generate-vitepress.mjs 里算完，再写进 Markdown 页面中，组件只做渲染。这样可以继续保持生成优先的站点结构。

最近更新必须基于源文件时间

如果直接读取 docs-site 文件时间，会因为每次生成都刷新时间戳，导致“最近更新”完全失真。

所以这一轮专门回到原始仓库目录读取 mtime。这虽然多了一次遍历，但换来了更可信的更新视图。

继续保留完整列表兜底

虽然本轮增加了很多卡片化入口，但没有去掉原有完整文档列表。

原因很简单：

• 卡片适合优先阅读
• 列表适合完整检索

两者并不是替代关系，而是互补关系。

自测结果

本轮完成后执行了：

• npm run docs:sync
• npm run build
• npm run preview -- --port 4173
• 首页、内容导航页、专题导航页、模块页、专题页访问校验

结果：通过。

本轮价值

M4 完成后，站点整体体验从“可用知识库”进一步走向“有导览能力的知识站”：

• 首页更有入口感
• 专题更有阅读顺序
• 模块页更有推荐感
• 最近更新能帮助内容维护者和读者快速识别变化