4.3 方言盘点与多平台策略

4.3 方言盘点与多平台策略

CommonMark 与 GFM 之外，还有 Multimarkdown、Pandoc Markdown、MDX 等各怀绝技的方言：有的管学术引用，有的管格式转换，有的把组件嵌进文档。这一节盘点它们的定位，并给出"一份稿子发多个平台"的实操策略。

方言地图

选型逻辑一句话：发布到哪里，就用哪里的方言。在文档站点工作，MDX 的组件能力是真生产力；同一份稿子要同时出网页和排版稿，Pandoc 一条转换命令解决（下一章细讲）。

Pandoc 方言的开关式扩展

Pandoc 的思路与众不同：基础语法之外，每个扩展都可以显式开关。例如脚注、删除线、定义列表默认启用，连表格都有五种写法（含带对齐和宽度的网格表）。这让"同一个解析器适配多种来源文档"成为可能——转换旧文档时，打开对方需要的扩展即可。

---
标题: 年度技术报告
作者: 平台工程组
---
​

上面这种 YAML 元数据头也是 Pandoc 与 Multimarkdown 的共有特性——文档的开头几行声明标题作者日期，转换时直接进目标格式的元信息，比正文里写"标题：xxx"优雅得多。

多平台发布的分层策略

一份稿子要同时发三个平台（比如代码仓库、知识库、公众号排版），我的做法是三层拆分：

第一层【核心正文】CommonMark 基础语法
        → 任何平台都不变形，绝不用平台专属记号写关键信息

第二层【通用增强】GFM 扩展（表格/任务列表/删除线）
        → 发布前确认各目标平台均支持

第三层【平台特化】脚注/数学/图表/折叠
        → 按平台单独维护，用变量或模板占位
​

特化层的维护成本容易失控，我的纪律是特化内容不超过全文一成，且永远不承载关键信息——图挂了脚注丢了，读者仍应能从正文读懂主线。

💡 关键直觉：可移植性不是"处处渲染得一模一样"，而是"处处都能读"。为了一模一样而砍掉所有增强，多数时候得不偿失。

方言能力对照速查图

一稿多发的工程化：模板与发布流水线

三层拆分是写作策略，多发量一大就需要工程化。把"一份稿子发多平台"做成可持续的流水线，核心是把内容与平台格式分离：正文只维护一份（核心层加通用增强），平台差异全部外置到发布环节。常见做法有三种，按投入递增排列。最轻的一种是"发布前替换"：特化内容用占位符写成（如 {{callout}}），每个平台配一份替换表，发布脚本把占位符换成该平台的容器语法。中等投入是 Pandoc 过滤器：以 Pandoc 为转换中枢，目标平台不支持的结构在过滤器里自动降级——表格降为列表、任务项降为文字前缀，一次编写处处生效。最重的是模板站点：MDX 加站点模板，所有平台差异收敛到组件库，正文完全平台无关。

选哪一档看发布频率与平台数量：一年发几篇、两个平台，手动替换最划算；每周发布、四个渠道，值得上过滤器；文档本身就是产品的一部分，才需要模板站点的投入。但无论哪一档，有一条铁律不变：发布流水线里必须有人工核对步骤——自动降级会有静默损失，尤其图片与脚注，发布前各平台预览一遍十分钟，比读者先发现错乱便宜得多。这也是方言问题最终极的答案：方言不会消失，能消除的只有"每次都手工对齐方言"这件事。

本节要点回顾

• 方言各有定位：GFM 管互联网、Pandoc 管转换、MDX 管工程、笔记方言管个人知识。
• Pandoc 的开关式扩展让一个解析器适配多种文档来源。
• 三层拆分：核心正文用基础语法、通用增强用 GFM、平台特化单独维护。
• 特化内容不承载关键信息，图和脚注全挂读者仍能读懂主线。

一次真实的多平台迁移走查

用一个迁移案例演示三层拆分怎么落地。起点是一份 Obsidian 写的内部手册：脚注、> [!WARNING] 标注、Mermaid 图、[[双链]] 全在用。目标是发布到公司文档站（GFM 加自定义容器）与 GitHub 仓库。迁移分三步。第一步盘点特化清单：双链 47 处、标注块 12 处、Mermaid 6 张、脚注 23 条。第二步分路处理：双链是纯私有语法且承载导航，批量替换为指向迁移后路径的普通链接；标注块替换为团队约定的 > ⚠️ 通用写法（GFM 层）；Mermaid 两平台都支持，保留；脚注 GitHub 支持，保留但预检编号漂移。第三步建立回归样本：每种特化语法挑一个代表段落，迁移后同时在两平台截图存档，作为后续再迁移的对照基准。

走查里最有价值的产出其实是第一步的特化清单——它顺便就是这份文档的"方言负债表"。此后每次新增内容，团队约定先查这张表再选语法，负债只减不增；季度迁移时清单清零重建。方言问题从"每次迁移的惊魂"变成"账目清晰的日常"，这正是多平台策略的全部意义。

白名单的维护：让策略可持续

三层拆分策略能坚持多久，取决于白名单的维护机制。建议白名单以一张表活在团队 wiki：每行一个特化语法，三列分别是"语法、允许使用的场景、负责验证的平台"。新增一行需要一次真实需求而非"看起来好用"；每季度复审时删掉半年没人用过的行——白名单的熵只增不减是常态，定期删减才能保持"看一眼就知道边界"的可读性。白名单还要与第 5 章的格式化工具配置对齐：工具自动放行的语法集合应等于白名单集合，两边不一致时以白名单为准修工具配置。机制立住后，方言策略就不再依赖任何人的记性。

方言登记表：把踩过的坑变成资产

多平台写作三个月后，建议团队开始维护一张"方言登记表"：每行记录一个真实踩到的差异（语法、平台、现象、规避写法）。它与 4.1 的排查树互补——排查树定位新问题，登记表沉淀旧答案。新人遇到怪象先查表，三十秒解决前人花半小时查过的问题。登记表要防两种腐化：条目不写规避写法（只有现象没有答案的表等于牢骚集），以及过期不删（平台修复后条目应标注或移除）。健康的登记表一年后大约二三十行，再多说明该认真考虑收敛写作子集了。