Pandoc转换深度解析：哪些内容能在标记语言转换中幸存

标记语言转换的"损耗"问题为何值得关注

随着 Pandoc 3.10.2 版本的发布，这款"文档转换界的瑞士军刀"再次引发技术社区的热议。无论是将 Markdown 转换为 HTML，还是反向操作，甚至将各类纯文本文件转换为 PDF，Pandoc 几乎都能胜任。但一个长期被低估的核心问题浮出水面：在不同标记语言之间转换时，究竟有多少内容能够"幸存"，又有多少会在转换过程中悄然丢失？

这绝非一个无关紧要的技术细节。对于需要跨平台、跨格式管理文档的团队和个人而言，转换损耗直接影响内容的可维护性与长期价值。本文将深入剖析 Pandoc 的转换机制，探讨现代标记语言的设计哲学，并解释 AST（抽象语法树）为何正在成为决定转换质量的关键因素。

Pandoc 的核心机制：以 AST 为中心的转换架构

为什么 AST 是 Pandoc 转换的灵魂

Pandoc 之所以能在数十种标记格式之间自由转换，秘诀在于它并非简单地做"文本替换"，而是将输入文档解析为一个统一的抽象语法树（AST）。这个中间表示层剥离了具体语法的外壳，只保留文档的结构与语义——标题、段落、列表、强调、链接、表格等核心元素。

抽象语法树是编译器理论中的核心概念，最早广泛应用于编程语言的编译与解释过程中。AST 将源代码或文档的语法结构以树形数据结构表示，其中每个节点代表一个语法构造（如表达式、语句、段落或标题），而"抽象"意味着它省略了具体的语法细节（如 Markdown 中的 # 号或 HTML 中的 <h1> 标签），只保留语义上有意义的信息。在文档转换领域，AST 的引入意味着将文档从"字符串操作"提升为"结构化操作"——类似于数据库查询比直接操作文本文件更可靠。Pandoc 的 AST 使用 Haskell 的代数数据类型定义，其核心类型包括 Block（块级元素如段落、标题、代码块）和 Inline（行内元素如加粗、链接、脚注），这种严格的类型系统确保了转换过程中的类型安全。

简单来说，Pandoc 的工作流程分为两步：

• 输入格式 → 解析为 AST
• AST → 渲染为输出格式

这种架构带来的直接好处是：任何能被 AST 完整表达的元素，就能"无损"地在支持该元素的目标格式之间流转。而转换损耗的本质，通常发生在两个环节——源格式的某些特性无法被完整解析进 AST，或者目标格式无法表达 AST 中的某些节点。

基于 AST 设计的标记语言转换保真度更高

一个关键发现值得强调：从设计之初就围绕清晰语法树构建的现代标记语言，在 Pandoc 转换中具有明显优势。

传统上，许多标记语言（尤其是早期 Markdown 的各种方言）语法定义模糊、边界情况处理不一致，解析结果难以标准化，转换时自然容易"失真"。而语法规则明确、解析结果可预测的语言，在与其他格式互转时保真度显著更高。

这也说明了一个重要原则：在评估"什么能在转换中幸存"时，语言的底层设计比表面语法更具决定性。

Markdown 的历史包袱与 Djot 的革新探索

从 Markdown 碎片化到 Djot 的诞生

Pandoc 的作者 John MacFarlane 同时也是 15 年前 Markdown 标准化工作的早期参与者之一。然而 Markdown 的"标准化"进程实际上演变成了相当程度的混乱——CommonMark、GitHub Flavored Markdown（GFM）、MultiMarkdown 等各种方言层出不穷，彼此之间存在微妙但恼人的语法差异。

Markdown 最初由 John Gruber 于 2004 年发布，其规范仅以一份非正式文档和一个 Perl 脚本实现的形式存在，缺乏形式化的语法定义。这导致了当输入包含嵌套列表缩进、行内 HTML 混合、链接引用嵌套等边界情况时，不同实现产生截然不同的输出。2014 年启动的 CommonMark 项目试图通过一份包含 600 多个测试用例的严格规范来解决这一问题，但其本身也引发了社区争议——Gruber 本人对"标准化"持保留态度，认为 Markdown 的灵活性正是其魅力所在。GFM 在 CommonMark 基础上增加了表格、任务列表、删除线等扩展，而 MultiMarkdown 则引入了脚注、元数据、数学公式等学术写作特性，这些方言的并存使得"Markdown 文件"实际上是一个语义模糊的概念。

正是出于对这种碎片化的深刻反思，MacFarlane 近年来推出了 Djot——一个被定位为"Markdown 精神继承者"的新兴标记语言。Djot 试图在保留 Markdown 可读性优势的同时，彻底解决其语法歧义和解析不一致的历史包袱，提供一套更严谨、更适合机器精确处理的规则体系。

Djot 于 2022 年由 MacFarlane 正式提出，其设计遵循几个核心原则：首先，消除解析时的回溯需求——Markdown 中诸如强调标记（* 和 _）的解析需要复杂的回溯算法来确定开启与关闭位置，而 Djot 通过更明确的规则实现了近乎线性时间的解析。其次，Djot 严格区分了块级元素和行内元素的标记方式，避免了 Markdown 中列表项与段落之间暧昧不清的关系。第三，Djot 引入了通用属性语法（类似于 HTML 的 class 和 id），使得任何元素都能附加元数据而无需回退到原始 HTML。从实现角度看，Djot 的参考解析器以 Lua 编写，输出标准化的 AST 表示，其规范文档以形式化的方式定义了每条解析规则的优先级和适用条件。

理想标记语言需要平衡的三个维度

一门理想的标记语言应当在以下几个维度取得良好平衡：

• 可读性（Readability）：人类阅读纯文本源码时应当直观易懂
• 可写性（Writeability）：书写过程自然流畅，不额外增加认知负担
• 机器可消费性（Machine-consumable）：能被程序精确解析，不存在歧义

此外，它还需要足够全面，能够表达从离线文档到在线内容的各类元素。这三者之间天然存在张力——过度追求机器友好可能牺牲书写体验（如 XML 虽然机器解析友好，但人类书写和阅读的体验极差），而过度简化又会限制表达能力（如纯 Markdown 无法原生表达脚注、定义列表或数学公式等常见需求）。Djot 的出现正是这种平衡探索的一次实质性尝试，它试图证明严格的解析规则与优良的书写体验并非不可调和。

开发者实战指南：格式选择与转换最佳实践

用 Dogfooding 验证你的工具链

"Dogfooding"（吃自己的狗粮）是检验工具可靠性的最佳方式——在实际项目中亲自使用你所推崇的格式和工具。只有当你真正用某种标记语言撰写文档、经历转换流程、面对实际损耗时，才能真正理解它的优势与局限所在。

降低 Pandoc 转换损耗的实用建议

对于日常需要处理文档格式转换的开发者与内容创作者，以下策略可以显著提升转换质量：

• 优先选择语法规则清晰的格式：如果内容需要频繁转换，选择解析规则明确的语言（如 CommonMark 或 Djot）能大幅降低损耗风险
• 提前了解 AST 的表达边界：转换前，先确认源格式和目标格式各自支持哪些元素，避免使用无法被目标格式表达的特性。例如，Markdown 的表格语法在转换为纯文本时会丢失对齐信息，而脚注在转换为不支持脚注的格式时可能被降级为括号注释
• 建立可复现的转换流程：善用 Pandoc 的模板和过滤器（filter）机制，让复杂转换变得可控、可维护、可追溯。Pandoc 的过滤器本质上是对 AST 进行变换的程序：Pandoc 将解析后的 AST 以 JSON 格式传递给外部过滤器程序，过滤器对其进行修改后返回新的 AST，Pandoc 再将修改后的 AST 渲染为目标格式。这种"管道式"架构允许用户在不修改 Pandoc 核心代码的情况下实现复杂的文档变换。Pandoc 支持两种过滤器接口：传统的 JSON 过滤器（可用任何语言编写）和性能更优的 Lua 过滤器（内嵌在 Pandoc 进程中运行，避免了 JSON 序列化的开销）
• 始终保留纯文本源文件：无论最终输出 HTML、PDF 还是 DOCX，都应以可读的纯文本标记源作为"单一真相源"，这才是内容长期价值的根本保障

将纯文本标记文件作为"单一真相源"（Single Source of Truth）的理念源自软件工程中的版本控制实践。与 DOCX 或 PDF 等二进制格式不同，纯文本文件可以被 Git 等版本控制系统高效地跟踪差异、合并变更和审查历史。这意味着文档的每一次修改都有完整的审计轨迹，多人协作时的冲突可以通过标准的 diff/merge 工具解决。此外，纯文本格式不依赖任何特定软件即可打开和编辑，具有极高的长期可读性——20 年前的纯文本文件今天依然可以轻松阅读，但 20 年前的专有格式文件可能已经无法打开。这种"面向未来"的特性对于学术出版、法律文档、技术文档等需要长期保存的内容尤为重要。

标记语言仍在演进，理解转换逻辑至关重要

Pandoc 3.10.2 的发布再次提醒我们，文档格式转换远非一个已经解决的问题。Markdown 十五年来的碎片化演变说明标准化之路充满曲折，而 Djot 等新语言的涌现则展示了社区对更优方案的不懈追求。

无论你是内容创作者还是开发者，理解"什么能在转换中幸存"以及背后的 AST 设计哲学，都能帮助你在纷繁的标记语言生态中做出更明智的选择。那个完美平衡可读、可写与可机读的标记语言或许仍在路上，但每一次探索都在推动整个文档工具生态稳步向前。