企业官网建设流程全解析

Pandoc 媒体维基表格转换实战：从 wikitable 语法到 HTML 输出的源码级解析

【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc

导读

本文以 pandoc 命令测试用例 test/command/10390.md 为主线，深入剖析 pandoc 的 MediaWiki 读取器（Reader）如何解析维基百科风格的wikitable表格语法，并将其转换为带表头、表体和标题的标准 HTML 表格。你将掌握 MediaWiki 表格语法的核心要素（caption、表头、行分隔符、单元格）、pandoc 内部表格解析的完整流程，以及 pandoc 命令测试框架的运行机制，从而能够独立验证和调试 MediaWiki 表格的转换行为。

一个完整的命令测试用例

test/command/10390.md是 pandoc 官方测试套件中的一个"命令测试"（command test）文件，它完整地展示了一次 MediaWiki 表格到 HTML 的转换：

% pandoc -f mediawiki {| class="wikitable" |+ Overview of basic table markup ! Key |- | Value |} ^D <table> <caption>Overview of basic table markup</caption> <thead> <tr> <th>Key</th> </tr> </thead> <tbody> <tr> <td>Value</td> </tr> </tbody> </table>

这个用例的意图非常清晰：验证pandoc -f mediawiki能把一个包含标题（caption）、表头（header）和普通单元格的最小 wikitable 正确转换为语义完整的 HTML 表格。输出中可以看到：

• <caption>对应表格的标题行|+；
• <thead>/<th>对应表头行!；
• <tbody>/<td>对应数据行|；
• 表格自身的class="wikitable"样式属性被读取但未出现在 HTML 中（因为 HTML 输出默认只保留结构与内容，样式类由用户自行通过模板或 CSS 处理）。

命令测试文件的结构约定

要读懂10390.md，需要先理解 pandoc 命令测试的格式约定，其解析逻辑定义在 test/Tests/Command.hs 的模块文档中：

1. 代码块第一行以%开头，后面是要执行的命令（本例为pandoc -f mediawiki）；
2. %之后到^D之前的所有行，会作为标准输入（stdin）传给该命令；
3. 单独的^D行表示输入结束（EOF 标记）；
4. ^D之后的内容是期望的标准输出（stdout）；
5. 若期望标准错误输出，则每行需以2>前缀开头；
6. 若期望非零退出码，最后一行需以=>前缀加退出码。

Tests.Command.tests会扫描 test/command 目录下所有.md文件，逐个提取代码块执行比对（见 test/Tests/Command.hs）。实际执行时命令中的pandoc会被替换为test-pandoc --emulate（见 test/Tests/Command.hs），以复用测试构建的二进制。这种"期望输出"与"实际输出"的 golden test 比对方式，保证了 MediaWiki 读取器的每次改动都会被严格回归验证。

MediaWiki 表格语法要素拆解

MediaWiki 表格（wikitable）是一种以{|起始、|}结束的管道标记语言。10390.md中的输入虽短，却覆盖了五个核心语法要素：

需要注意!与|均可出现在行首或行中：行首写法表示"此单元格是该行的第一个"，行中写法（如| Key || Value）表示继续追加单元格。

源码级解析：MediaWiki 读取器如何"读懂"表格

表格解析的核心实现在 src/Text/Pandoc/Readers/MediaWiki.hs 的table解析器（第 270-307 行）。整个流程可以概括为六个阶段：

1. 表格开始与样式解析

tableStart（第 331-335 行）要求{|出现在行首（guardColumnOne），随后parseAttrs读取class="wikitable"之类的键值属性。width属性会被特殊处理：parseWidth（第 399-403 行）只接受百分数值，如width="75%"会被解析为 0.75 的相对列宽。

2. 标题（caption）解析

tableCaption（第 355-363 行）匹配行首的|+，其后的所有行内内容（inline 元素）会被收集为表格标题，最终通过B.simpleCaption挂到 Pandoc 的Table结构上。

3. 表头探测

解析器通过lookAhead (skipSpaces *> char '!')（第 284 行）向前窥视：如果表格第一行以!开头，则判定存在表头行，该行进入TableHead；否则整行数据归入TableBody（第 297-299 行）。

4. 单元格解析与对齐、跨行列

tableCell（第 369-397 行）处理每个单元格：cellsep识别|或!分隔符及align、rowspan、colspan等属性。其中：

• align值left/right/center映射为对应的列对齐方式（第 377-381 行）；
• rowspan/colspan通过safeRead读取为数值（第 382-385 行）；
• 其余未处理属性（如style）会原样保留为单元格属性。

calculateAlignments（第 309-313 行）会把每个单元格的对齐方式按colspan复制，从而得到完整的列对齐列表。

5. 行分隔

rowsep（第 337-342 行）匹配行首的|-，允许连续多个-以及行属性、HTML 注释。table主体通过many $ try $ rowsep *> tableRow循环读取所有数据行（第 294 行）。

6. 列宽计算

解析器按单元格width属性汇总每列宽度，widths为 0 的列会被均分剩余宽度（defaultwidth，见 第 288-292 行），最后用compactifyTable规范化表格结构，输出 Pandoc 内部TableAST。

从内部 AST 到 HTML 输出

table解析器产出的 PandocTableAST（含TableHead、TableBody、TableFoot与 caption）在 HTML 写入器中被还原为语义化标签。核心转换位于 src/Text/Pandoc/Writers/HTML.hs 与tableToHtml（第 1149 行起）：

• caption 渲染为<caption>（第 1150-1156 行）；
• 表头行渲染为<thead>中的<tr><th>（tableHeadToHtml，第 1201 行）；
• 数据行渲染为<tbody>中的<tr><td>（tableBodyToHtml，第 1188 行）。

这正是10390.md期望输出中<caption>、<thead>、<tbody>三级结构的直接来源。

同主题的扩展用例

除10390.md外，测试目录下还有若干 MediaWiki 相关用例，可作为深入学习的对照材料：

• test/command/mediawiki_behavior_switches.md：验证____INDEX____、__NOINDEX__等"魔法词"（behavior switches）不会被误解析，而是作为普通文本处理（只有__INDEX__/__NOINDEX__等被识别的魔法词才会被剥离）；
• test/command/figures-mediawiki.md：MediaWiki 图片语法在转换中的行为；
• test/command/6119.md、test/command/7145.md 等编号用例：覆盖 MediaWiki 读取器的各类边界场景；
• 全量 MediaWiki 读取器单元测试位于 test/Tests/Readers/MediaWiki.hs，HTML 表格输出对照可参考 test/command/tables.mediawiki。

如何在本地复现与验证

在已构建 pandoc 的源码目录下，可以直接执行相同的命令复现该测试：

# 用 printf 构造 stdin 输入，等价于测试文件中 ^D 之前的内容 printf '%s\n' ' {| class="wikitable"' ' |+ Overview of basic table markup' ' ! Key' ' |-' ' | Value' ' |}' \ | pandoc -f mediawiki # 或使用原生 AST 输出，观察表格内部结构 printf '%s\n' ' {| class="wikitable"' ' |+ Overview of basic table markup' ' ! Key' ' |-' ' | Value' ' |}' \ | pandoc -f mediawiki -t native

若要跑完整命令测试套件，可在test目录下执行test-pandoc（其入口为 test/test-pandoc.hs），它会按 test/Tests/Command.hs 的规则对 test/command 下所有.md用例逐一做 golden 比对。

小结

test/command/10390.md以最小化的输入完整覆盖了 MediaWiki wikitable 语法中"表格开始 → 标题 → 表头 → 行分隔 → 数据单元格 → 表格结束"的完整链路，并验证了 pandoc 会将其转换为符合语义的<caption>/<thead>/<tbody>HTML 结构。透过 src/Text/Pandoc/Readers/MediaWiki.hs 中table、tableCaption、tableRow、tableCell、rowsep等解析器，我们可以清晰看到每一个语法要素在源码中的对应实现，这为理解 MediaWiki 读取器的整体设计、扩展其表格能力（如嵌套表格、跨行列）以及排查转换异常提供了可靠的技术参照。

【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc