技术博客：把 Markdown 知识库站点补齐搜索、SEO 与 GitHub Pages 发布能力

为什么这一轮不再继续加导航

前两轮改造已经解决了两个核心问题：

• 让仓库中的 Markdown 内容可以稳定接入 VitePress
• 让读者可以按模块和专题进入内容

如果继续一味叠加入口，站点确实会越来越“能逛”，但还不够“能发布”。

一个真正能对外使用的静态知识站，至少还需要解决四件事：

1. 搜索结果要尽量有用
2. 页面标题和摘要要稳定
3. 构建结果要有 sitemap / robots 这类基础产物
4. 发布 workflow 要对准真正的站点构建产物

所以 M3 的思路，是从“结构可浏览”切换到“站点可发布”。

先解决一个很隐蔽的问题：占位页污染搜索

为了保证历史 Markdown 脏数据不阻塞构建，生成脚本会为一些空文件或不可读取文件生成占位页。

这件事对构建很重要，但会带来一个副作用：如果这些占位页也进入本地搜索索引，用户搜索时就可能先看到“这个文件为空”的说明页，而不是真正有内容的文档。

解决方式并不复杂，但很关键：

• 继续保留占位页
• 通过 frontmatter 为占位页增加 search: false
• 同时关闭这些页面的目录大纲展示

这样站点的鲁棒性和搜索质量就不会互相打架。

让自动生成页面也有 SEO 意识

很多静态站点的 SEO 缺失，不是因为没有配置能力，而是因为自动生成页面只顾着“生成出来”，没有把 title 和 description 一起设计进去。

这轮改造里，我把下面几类页面都补了页面级元信息：

• 首页
• 内容导航页
• 专题导航页
• 模块总览页
• 专题详情页
• 占位页

这样至少能保证：

• 浏览器标题更稳定
• 分享时摘要更完整
• 搜索引擎拿到的是更清晰的页面语义

用 transformHead 统一收敛 canonical 和社交卡片

页面一多，最怕的就是每个页面自己维护 meta 标签，最后不是漏配，就是风格不统一。

这一轮直接把 canonical、Open Graph 和 Twitter Card 的主要逻辑收敛到 transformHead，再配合统一的站点生产地址和页面相对路径去生成 URL。

这样做的好处是：

• 新增页面时不需要重复手填元信息结构
• 首页、模块页、专题页都能继承同一套规则
• 后续切域名或切部署地址时，只需要改统一配置

GitHub Pages workflow 不能再上传整个仓库

原先仓库里的 Pages workflow 最大的问题，不是它“不能运行”，而是它上传的并不是 VitePress 构建产物。

对于 VitePress 这类静态站，真正应该部署的是：

• 安装依赖后的构建结果
• 也就是 docs-site/.vitepress/dist

所以这一轮把 workflow 切到了标准的静态站发布流程：

• checkout
• setup node
• npm ci
• npm run docs:build
• 上传 dist
• deploy pages

这一步完成后，仓库内的发布链路才真正和 VitePress 站点对齐。

这一轮最值得保留的方法

如果以后还会把“旧资料仓库”重构成站点，我会继续保留这几个做法：

• 优先做“生成优先”，而不是手工维护大量页面
• 用占位页兜底脏数据，但不要让它们污染搜索
• 把页面级元信息也纳入生成逻辑
• 让发布 workflow 直接围绕最终构建产物工作

这套方法的价值在于：它不是一次性的页面美化，而是在给知识库建立一个可持续演进的底座。

结语

从 M0 到 M3，这个仓库里的 Markdown 资料已经从“分散文件夹”逐渐变成了“可构建、可浏览、可检索、可发布”的知识站点。

接下来如果继续推进，更值得做的方向会是：

• 首页表达继续升级
• 重点专题继续深化
• 自动化校验和发布观察能力继续补齐
• 对高价值内容做二次编辑和专题化输出

也就是说，后面的工作重心会越来越从“让站点跑起来”，转向“让知识真正更容易被读到”。