Markdown 文档工程、方言治理与发布手册

Markdown 文档编译与方言边界从文本源、解析器和扩展语法，到链接校验、站点构建、发布证据与迁移恢复。高清原图

Markdown 的优势是源文件可读、diff 清楚、工具选择多。它的风险也来自同一个地方：名字相同，解析结果未必相同。CommonMark 定义的是语法基线，表格、任务列表、脚注、标题锚点和原始 HTML 往往由 GFM 或站点插件补充。团队真正需要固定的不是“使用 Markdown”，而是哪个解析器以哪些配置处理哪些扩展。

先把方言写成可执行合同

文档合同至少说明文件范围、字符编码、换行策略、允许的扩展、原始 HTML 策略、链接规则、代码块语言和标题锚点算法。CommonMark 当前规范可作为最小语法参照，但不能替代实际站点的配置。架构师更关心可迁移语义：标题、段落、链接、图片和围栏代码块通常最稳定，依赖某个渲染器的容器语法和组件标签则应被视为平台扩展。

一个最小项目把解析器和检查器装进仓库，而不是要求每位作者单独安装全局命令。下面的配置把 Markdown 校验变成项目依赖，也让 CI 和本机使用同一版本。

{
  "scripts": {
    "docs:lint": "markdownlint-cli2 \"docs/**/*.md\"",
    "docs:links": "node scripts/check-links.mjs",
    "docs:build": "vuepress-vite build docs"
  },
  "devDependencies": {
    "markdownlint-cli2": "<锁定版本>"
  }
}

配置影响应当通过样例固定，而不是靠口头解释。仓库可以保留一页语法夹具，覆盖标题、相对链接、表格、代码围栏、转义字符和原始 HTML；升级解析器时比较生成结构，而不是只看构建是否返回成功。

正向验证必须覆盖发布链

正向实验从一份很小的文档开始，包含一个相对链接、一张本地图片、一个带语言标识的代码块和两个可被引用的标题。本地先执行 lint 与站点构建，再从输出目录确认页面、锚点、图片和代码高亮都存在。成功证据应包含命令、退出码、来源提交和输出位置，截图只能补充视觉结果。

npm ci
npm run docs:lint
npm run docs:links
npm run docs:build
git diff --exit-code

项目接入 CI 后，拉取请求只运行受影响范围的快速检查，主分支再执行完整站点构建。缓存可以保存依赖下载，但不应缓存未经校验的最终 HTML。发布任务使用只读仓库凭证；Markdown 正文不应该接触部署 Token。

反向证据比“本机正常”更有价值

最有用的反例是故意写一个失效相对链接、重复标题或未闭合代码围栏，确认门禁会以非零退出码失败，并且错误能定位到文件与行。另一个实验是在 IDE 预览和站点渲染器中放入同一段扩展语法，记录两者差异。错误被稳定捕获后，规则才算存在；靠评审者肉眼发现不叫自动治理。

排障时先区分解析、资源解析和发布三层。语法错误通常在解析阶段出现；图片 404 多半来自路径、base 或大小写；本地正常而 CI 失败常见于未提交文件、平台大小写差异或依赖未锁定。保留最小失败文件、实际配置和构建日志，避免在原文上连续试改后丢失证据。

原始 HTML、链接与数据边界

Markdown 可以包含原始 HTML，并不代表所有发布入口都应允许它。公开站点应由可信构建器清洗危险标签与 URL 协议；用户可提交内容时，必须把 Markdown 当作不可信输入。远程图片会泄露访问时间和客户端信息，内部域名会暴露网络结构，示例中的 Cookie、Token 与客户数据则会直接进入 Git 历史。

权限模型应保持简单：作者只修改文本和受控资源，构建服务只读取仓库并写临时输出，发布身份只写目标站点。外链检查器如果需要联网，应限制协议、超时、响应大小和目标范围。敏感内容扫描不能代替人工审查，但能阻止最明显的凭证进入长期历史。

迁移、清理与恢复

迁移到另一套站点之前，先建立语法使用清单，再按影响处理平台扩展。稳定语义直接迁移，特殊容器和自定义锚点需要转换，无法等价表达的组件应保留原始页面和决策记录。旧 URL 通过重定向继续可达，不能只删除旧文件并期待搜索索引自动修复。

清理旧工具时，先确认新环境能够从干净检出完成安装、验证和构建，再移除旧依赖、插件与缓存。回滚条件要明确：如果标题锚点、代码块或重要链接出现大面积变化，恢复旧解析器锁文件和构建配置。恢复演练的结果应落入仓库，而不是停在某台机器的浏览器缓存里。

团队治理看可维护性而不是语法偏好

Markdown 的容量成本主要落在构建时间、图片体积、链接数量和规则复杂度。owner 应关注失败率、过期页面、孤立页面和构建时长，而不是追求规则数量。规则新增要对应真实风险，例外要有范围和退出条件；长期维护中，一条能解释、能自动验证的规则，比十条只在规范里出现的要求更可靠。

最终交付不是“仓库里有一批 .md 文件”，而是文本在确定解析器下能重建站点，链接和资源可验证，权限与数据边界清楚，迁移时能说明哪些语义稳定、哪些扩展需要处置。这才是 Markdown 作为工程资产的机制边界。