22 站点写作工具链
Markdown 文件能在编辑器里预览，不等于它已经成为可维护的知识站点。一次真实发布还要处理 frontmatter 类型、标题层级、组件和 Mermaid 渲染、图片路径、路由与重定向、侧边栏顺序、搜索索引、静态构建、子路径部署和缓存清理。任何一层只在开发服务器上“看起来正常”，都可能在 CI、对象存储或旧链接访问时暴露问题。
站点写作工具链的目标，是把内容当作可编译源文件。作者提交 Markdown、元数据和受控资产；框架解析内容并生成路由；导航与搜索从明确事实源构建；CI 检查草稿、死链、敏感信息和关键页面；最终静态产物经过浏览器、移动视口和旧路由验证后才发布。失败时能够定位到源、配置、插件、构建或部署层，而不是重新手工上传一份文件。
从源文件到可访问页面
这条链不要求所有项目使用同一个框架，但要求输入、转换和输出都能被验证。框架版本、Node 支持线、主题插件、Markdown 扩展和构建参数属于构建环境；文章元数据、图片和路由属于内容契约；CDN、base、缓存和重定向属于交付环境。把三者混成一份个人配置，升级和迁移时就无法判断哪一层改变了行为。
阅读路径
| 站点现场 | 入口 | 要建立的能力 |
|---|---|---|
| 项目已经使用 VuePress，却没人敢升级主题和插件 | VuePress | 初始化、目录、配置、主题插件、构建、调试与升级治理 |
| 需要新建或迁移站点，不清楚替代框架边界 | VitePress 与 Docusaurus | 最小站点、内容模型、生态边界、迁移成本与选型标准 |
| 元数据写错仍能提交，图示到构建时才失败 | frontmatter、Markdown 与 Mermaid | schema、标题、链接、代码、图示、安全与渲染门禁 |
| 本地图片正常，子路径部署后全部 404 | 图片与公开路径 | public、base、相对路径、构建 URL、缓存和响应式验证 |
| 草稿被发布，侧栏漏页，旧链接突然失效 | 草稿、导航与构建检查 | 状态、顺序、导航、重定向、关键页面和 CI 发布闸门 |
| 搜索结果过期，归档内容仍能从索引打开 | 搜索与知识维护 | 索引模型、中文检索、归档、缓存清除、质量和退出治理 |
开发预览与生产构建是两种证据
开发服务器为编辑反馈优化，常常在内存中处理路由、容忍动态模块，并通过回退机制掩盖大小写或路径错误。生产构建要把每个页面、资源和客户端模块变成确定文件，再由静态服务器按真实 base 和缓存规则提供。因此最小验证必须同时包含 dev 与 build，并直接检查构建目录中的目标 HTML、图片和重定向文件。
构建成功也不是发布完成。浏览器要在与生产一致的子路径打开关键页面，验证导航、图片、代码高亮、Mermaid、搜索、移动端布局和旧 URL。若站点依赖客户端 JavaScript，静态 HTML 存在只能证明生成成功，不能证明 hydration、交互和索引加载正常。
内容契约必须可检查
frontmatter 是页面与主题、导航、搜索、时间线和站点地图之间的接口。布尔值写成字符串、顺序号重复、草稿字段拼错或具体日期进入正式正文，都可能被 YAML 正常解析，却产生错误业务行为。团队应为允许字段、类型、枚举和互斥关系定义 schema，再用项目脚本检查跨文件唯一性与引用完整性。
Markdown 同样不是无约束文本。标题层级决定目录和可访问性，链接决定知识图关系，代码块语言影响高亮和构建告警，HTML 与客户端组件影响安全和 SSR。Mermaid 图还要区分解析失败、不安全内容、主题渲染和移动端可读性。语法检查只负责第一层，关键页面构建与浏览器验证负责最终行为。
路由、导航和搜索不是三份目录
路由回答页面在哪里，导航回答读者怎样发现它，搜索回答内容怎样被检索。三者可以生成不同视图，却必须共享稳定页面身份、标题和发布状态。手写三份列表会产生漏挂、重复、旧路径失效和已归档内容仍进入索引等漂移。
每次目录重组都要保留旧 URL 清单，明确永久重定向、临时兼容或下线状态，并验证重定向不会形成循环和链式跳转。搜索索引应只消费本次发布清单，删除旧文档后同步清除旧索引、Service Worker、CDN 与浏览器缓存，不能把“页面 404”误当成敏感内容已经消失。
插件与构建代码拥有内容权限
主题、Markdown 插件、搜索插件和构建脚本可以读取全部文章、环境变量和静态资产，还能向生成页面注入脚本。它们属于供应链代码，不是普通编辑器扩展。依赖要固定、审查变更、限制生命周期脚本和网络出口；构建日志、错误页面和 source map 不得泄露本地路径、内部域名、令牌或未发布内容。
外部搜索、评论、统计和托管服务还会接收页面正文、URL、访问日志或用户查询。接入前画清数据路径、地区、保留期、删除和退出方式；停用时不仅删除前端脚本，还要撤销密钥、清除远端索引和验证历史构建不再加载旧服务。
团队运行底线
- 本地开发、生产构建和真实托管路径各有可复制的验证命令与预期结果。
- frontmatter、标题、链接、图片、草稿、顺序和敏感信息在提交前有自动门禁。
- 路由、导航与搜索共享发布清单，目录调整同时维护旧 URL 和重定向测试。
- 每次构建保存框架、Node、依赖锁、配置摘要、产物哈希和关键页面 smoke 证据。
- 主题或插件升级先在固定样本站点验证，再切换正式构建，并保留上一个可部署产物。
- 搜索、CDN、对象存储和第三方脚本都有 owner、费用、审计、清理与退出计划。
当一篇文章能够从源文件稳定走到页面、导航、搜索和旧链接，并且每一步都有机器证据和恢复入口时，知识站点才是一套工程系统；否则它仍然只是一次规模更大的本地预览。