Pandoc AsciiDoc 输出中的链接宏处理--wrappreserve下的隐式链接与link:前缀规则【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc导读本文以 pandoc 官方回归测试用例 test/command/10105.md 为切入点深入剖析 Pandoc 在把 Markdown 链接转换为 AsciiDoc/Asciidoctor 输出时的两条核心规则哪些 URL 可以输出为隐式implicit链接宏、哪些必须显式加上link:前缀以及--wrappreserve对链接行输出的影响。读完本文你将理解http:/https:与ftps:等非默认协议在 AsciiDoc 输出中的差异掌握判断link:前缀是否需要的底层逻辑并能结合源码在 src/Text/Pandoc/Writers/AsciiDoc.hs 中追溯这条规则的完整实现。一、用例本体一条命令两组输出回归测试 test/command/10105.md 全文如下% pandoc -t asciidoc --wrappreserve [link](https://example.com) link ^D https://example.com[link] link:ftps://example.com[link]这是一个典型的 pandoc 命令行测试command test文件其结构为% pandoc -t asciidoc --wrappreserve要执行的命令输出格式为asciidoc并开启--wrappreserve换行模式随后的普通文本标准输入stdin中的 Markdown 源文档包含两个链接[link](https://example.com)与link^D结束标准输入最后两行期望的输出即https://example.com[link]与link:ftps://example.com[link]。输入与输出一一对应测试意图非常清晰同样是绝对 URL 链接https:协议走隐式链接宏而ftps:协议必须显式加link:前缀。关于测试框架pandoc 的命令行测试通过 test/Command.hs 驱动测试脚本与期望输出按上述约定放在同一.md文件中。本文用例属于 test/command 目录下众多回归测试之一专门用于锁定 AsciiDoc 写器的链接宏行为防止未来重构时回归。二、从 Markdown 链接到 AsciiDoc 链接宏2.1 AsciiDoc 的两种链接写法AsciiDoc/Asciidoctor 中链接有两种等价写法隐式链接宏implicit macroURL[link text]例如https://example.com[link]。要求 URL 本身能被 AsciiDoc 解析器识别为可接受的链接目标。显式链接宏explicit macrolink:URL[link text]例如link:ftps://example.com[link]。link:前缀强制把目标当作链接处理适用于相对路径、自定义协议等无法被隐式识别的目标。pandoc 的 AsciiDoc 写器正是根据目标的协议/形态决定采用哪种写法。2.2 写器中的判定逻辑核心实现在 src/Text/Pandoc/Writers/AsciiDoc.hs 的inlineToAsciiDoc对Link元素的分支中源码注释本身就给出了两条对照示例-- relative: link:downloads/foo.zip[download foo.zip] -- abs: http://google.cod[Google] -- or myemail.com[email john]判定是否需要在前面加link:前缀的代码为let needsLinkPrefix case parseURI (T.unpack src) of Just u - uriScheme u notElem [http:,https:, ftp:, irc:, mailto:] _ - True逻辑可以拆解为两步用Network.URI.parseURI解析链接目标src若解析成功检查uriScheme即协议名是否在豁免列表[http:, https:, ftp:, irc:, mailto:]中在列表中则无需前缀输出隐式宏不在列表中则需要link:前缀若解析失败例如相对路径downloads/foo.zip则一律需要link:前缀。这正是 10105 号用例所验证的行为https://example.com的 scheme 是https:命中豁免列表输出https://example.com[link]ftps://example.com的 scheme 是ftps:不在列表中输出link:ftps://example.com[link]。需要特别说明虽然ftps:是 IANA 官方注册协议在 src/Text/Pandoc/URI.hs 的schemes集合中可见但 pandoc 的 AsciiDoc 写器在link:前缀判定上使用了一个独立、更窄的豁免列表只覆盖http/https/ftp/irc/mailto五个协议。这体现了写器层面的选择只对这些最常用、AsciiDoc 解析器可隐式识别的协议输出隐式宏其余协议包括ftps:统一交给link:显式宏处理保证在 Asciidoctor 中渲染结果可靠。2.3 mailto 的特例与自链接优化在上述豁免列表之外mailto:还享受两处特例处理src/Text/Pandoc/Writers/AsciiDoc.hslet srcSuffix fromMaybe src (T.stripPrefix mailto: src) let useAuto case txt of [Str s] | escapeURI s srcSuffix - True _ - Falsemailto:前缀会在输出时被剥掉srcSuffix因为 AsciiDoc 的mailto:宏本身需要保留该前缀如果链接文本恰好等于去除mailto:后的地址如[fooexample.com](mailto:fooexample.com)则useAuto为真输出纯文本fooexample.com即可AsciiDoc 会自动识别为邮件链接无需任何宏escapeURI定义于 src/Text/Pandoc/URI.hs负责转义空白与 |{}[]^ 等字符保证链接文本与目标可安全比较。类似地当--出现在链接目标中时needsPassthrough为真输出会退化为link:...[...]的 pass-through 形式避免双连字符触发 AsciiDoc 的替代substitution机制src/Text/Pandoc/Writers/AsciiDoc.hs。三、--wrappreserve在用例中的作用10105 用例显式传入了--wrappreserve这一点并非无关紧要。3.1 三种换行模式根据 MANUAL.txt 的说明模式行为--wrapauto默认按--columns默认 72 列自动折行--wrapnone完全不换行--wrappreserve尽量保留源文档中的非语义换行在 AsciiDoc 写器内部换行模式由writerWrapText决定。对应实现可见 src/Text/Pandoc/Writers/AsciiDoc.hs 对SoftBreak的处理inlineToAsciiDoc opts SoftBreak case writerWrapText opts of WrapAuto - return space WrapPreserve - return cr WrapNone - return space即--wrappreserve下源文档中的软换行SoftBreak会在输出中保留为换行符而auto/none模式下软换行被折叠为空格。同时pandocToAsciiDoc在WrapAuto时才会依据--columns计算列宽src/Text/Pandoc/Writers/AsciiDoc.hs。3.2 对测试稳定性的意义用例中每行各含一个链接、源文档不含软换行因此preserve模式的作用主要体现在输出行的确定性每个链接独立成行、不被折行或合并期望输出与输入一一对应便于精确断言。若改为默认的auto模式短行不会触发折行结果通常相同但使用preserve消除了列宽变化带来的潜在干扰让测试聚焦于链接宏本身的判定逻辑——这正是该测试选择此参数的原因。四、与源码、测试的相互印证4.1 写器单元测试中的对应覆盖除了命令行回归测试 10105AsciiDoc 写器还有专门的单元测试套件 test/Tests/Writers/AsciiDoc.hs。其中asciidoc unpack . purely (writeAsciiDocLegacy def) . toPandoc asciidoctor unpack . purely (writeAsciiDoc def) . toPandocasciidoc走writeAsciiDocLegacy对应asciidoc_legacy格式面向asciidoc-pyasciidoctor走writeAsciiDoc对应现代asciidoc格式面向 Asciidoctor。这与 MANUAL.txt 对输出格式的划分一致asciidoc是 Asciidoctor 解释的现代 AsciiDocasciidoc_legacy是asciidoc-py解释的旧版而asciidoctor只是asciidoc的废弃别名。10105 用例使用的-t asciidoc即现代格式。4.2 相关源码文件速查关注点位置link:前缀判定与链接输出src/Text/Pandoc/Writers/AsciiDoc.hs换行模式对 SoftBreak 的影响src/Text/Pandoc/Writers/AsciiDoc.hsescapeURI与 IANA scheme 列表src/Text/Pandoc/URI.hs、src/Text/Pandoc/URI.hs--wrap选项说明MANUAL.txt命令行测试框架test/Tests/Command.hsAsciiDoc 写器单元测试test/Tests/Writers/AsciiDoc.hs五、实战小结与自查清单在实际使用pandoc -t asciidoc或-t asciidoctor输出链接时可以对照以下规则自查目标为http:/https:/ftp:/irc:/mailto:协议且是绝对 URL输出隐式链接宏URL[text]不加前缀目标是相对路径如downloads/foo.zipparseURI解析失败输出link:downloads/foo.zip[text]目标为其他协议如ftps:、ssh:、doi:等虽然可能是合法 IANA scheme但不在写器豁免列表内输出link:URL[text]mailto:链接且文本等于地址本身输出裸文本由 AsciiDoc 自动识别为邮件链接链接目标含--退化为link:...[...]pass-through 写法。通过 test/command/10105.md 这个短小精悍的回归用例我们可以一眼看穿 pandoc AsciiDoc 写器在链接宏选择上的设计取舍对常用协议追求简洁的隐式宏对非常用协议和相对路径则退回显式link:宏从而兼顾输出可读性与渲染可靠性。当你在自己的文档转换流程中遇到link:前缀意外出现时不妨回到这份豁免列表判断目标协议是否属于那五个白名单协议即可。【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/18 16:10:29 · 阅读 1.2k Pandoc AsciiDoc 输出中的链接宏处理：`--wrap=preserve` 下的隐式链接与 `link:` 前缀规则
Pandoc AsciiDoc 输出中的链接宏处理--wrappreserve下的隐式链接与link:前缀规则【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc导读本文以 pandoc 官方回归测试用例 test/command/10105.md 为切入点深入剖析 Pandoc 在把 Markdown 链接转换为 AsciiDoc/Asciidoctor 输出时的两条核心规则哪些 URL 可以输出为隐式implicit链接宏、哪些必须显式加上link:前缀以及--wrappreserve对链接行输出的影响。读完本文你将理解http:/https:与ftps:等非默认协议在 AsciiDoc 输出中的差异掌握判断link:前缀是否需要的底层逻辑并能结合源码在 src/Text/Pandoc/Writers/AsciiDoc.hs 中追溯这条规则的完整实现。一、用例本体一条命令两组输出回归测试 test/command/10105.md 全文如下% pandoc -t asciidoc --wrappreserve [link](https://example.com) link ^D https://example.com[link] link:ftps://example.com[link]这是一个典型的 pandoc 命令行测试command test文件其结构为% pandoc -t asciidoc --wrappreserve要执行的命令输出格式为asciidoc并开启--wrappreserve换行模式随后的普通文本标准输入stdin中的 Markdown 源文档包含两个链接[link](https://example.com)与link^D结束标准输入最后两行期望的输出即https://example.com[link]与link:ftps://example.com[link]。输入与输出一一对应测试意图非常清晰同样是绝对 URL 链接https:协议走隐式链接宏而ftps:协议必须显式加link:前缀。关于测试框架pandoc 的命令行测试通过 test/Command.hs 驱动测试脚本与期望输出按上述约定放在同一.md文件中。本文用例属于 test/command 目录下众多回归测试之一专门用于锁定 AsciiDoc 写器的链接宏行为防止未来重构时回归。二、从 Markdown 链接到 AsciiDoc 链接宏2.1 AsciiDoc 的两种链接写法AsciiDoc/Asciidoctor 中链接有两种等价写法隐式链接宏implicit macroURL[link text]例如https://example.com[link]。要求 URL 本身能被 AsciiDoc 解析器识别为可接受的链接目标。显式链接宏explicit macrolink:URL[link text]例如link:ftps://example.com[link]。link:前缀强制把目标当作链接处理适用于相对路径、自定义协议等无法被隐式识别的目标。pandoc 的 AsciiDoc 写器正是根据目标的协议/形态决定采用哪种写法。2.2 写器中的判定逻辑核心实现在 src/Text/Pandoc/Writers/AsciiDoc.hs 的inlineToAsciiDoc对Link元素的分支中源码注释本身就给出了两条对照示例-- relative: link:downloads/foo.zip[download foo.zip] -- abs: http://google.cod[Google] -- or myemail.com[email john]判定是否需要在前面加link:前缀的代码为let needsLinkPrefix case parseURI (T.unpack src) of Just u - uriScheme u notElem [http:,https:, ftp:, irc:, mailto:] _ - True逻辑可以拆解为两步用Network.URI.parseURI解析链接目标src若解析成功检查uriScheme即协议名是否在豁免列表[http:, https:, ftp:, irc:, mailto:]中在列表中则无需前缀输出隐式宏不在列表中则需要link:前缀若解析失败例如相对路径downloads/foo.zip则一律需要link:前缀。这正是 10105 号用例所验证的行为https://example.com的 scheme 是https:命中豁免列表输出https://example.com[link]ftps://example.com的 scheme 是ftps:不在列表中输出link:ftps://example.com[link]。需要特别说明虽然ftps:是 IANA 官方注册协议在 src/Text/Pandoc/URI.hs 的schemes集合中可见但 pandoc 的 AsciiDoc 写器在link:前缀判定上使用了一个独立、更窄的豁免列表只覆盖http/https/ftp/irc/mailto五个协议。这体现了写器层面的选择只对这些最常用、AsciiDoc 解析器可隐式识别的协议输出隐式宏其余协议包括ftps:统一交给link:显式宏处理保证在 Asciidoctor 中渲染结果可靠。2.3 mailto 的特例与自链接优化在上述豁免列表之外mailto:还享受两处特例处理src/Text/Pandoc/Writers/AsciiDoc.hslet srcSuffix fromMaybe src (T.stripPrefix mailto: src) let useAuto case txt of [Str s] | escapeURI s srcSuffix - True _ - Falsemailto:前缀会在输出时被剥掉srcSuffix因为 AsciiDoc 的mailto:宏本身需要保留该前缀如果链接文本恰好等于去除mailto:后的地址如[fooexample.com](mailto:fooexample.com)则useAuto为真输出纯文本fooexample.com即可AsciiDoc 会自动识别为邮件链接无需任何宏escapeURI定义于 src/Text/Pandoc/URI.hs负责转义空白与 |{}[]^ 等字符保证链接文本与目标可安全比较。类似地当--出现在链接目标中时needsPassthrough为真输出会退化为link:...[...]的 pass-through 形式避免双连字符触发 AsciiDoc 的替代substitution机制src/Text/Pandoc/Writers/AsciiDoc.hs。三、--wrappreserve在用例中的作用10105 用例显式传入了--wrappreserve这一点并非无关紧要。3.1 三种换行模式根据 MANUAL.txt 的说明模式行为--wrapauto默认按--columns默认 72 列自动折行--wrapnone完全不换行--wrappreserve尽量保留源文档中的非语义换行在 AsciiDoc 写器内部换行模式由writerWrapText决定。对应实现可见 src/Text/Pandoc/Writers/AsciiDoc.hs 对SoftBreak的处理inlineToAsciiDoc opts SoftBreak case writerWrapText opts of WrapAuto - return space WrapPreserve - return cr WrapNone - return space即--wrappreserve下源文档中的软换行SoftBreak会在输出中保留为换行符而auto/none模式下软换行被折叠为空格。同时pandocToAsciiDoc在WrapAuto时才会依据--columns计算列宽src/Text/Pandoc/Writers/AsciiDoc.hs。3.2 对测试稳定性的意义用例中每行各含一个链接、源文档不含软换行因此preserve模式的作用主要体现在输出行的确定性每个链接独立成行、不被折行或合并期望输出与输入一一对应便于精确断言。若改为默认的auto模式短行不会触发折行结果通常相同但使用preserve消除了列宽变化带来的潜在干扰让测试聚焦于链接宏本身的判定逻辑——这正是该测试选择此参数的原因。四、与源码、测试的相互印证4.1 写器单元测试中的对应覆盖除了命令行回归测试 10105AsciiDoc 写器还有专门的单元测试套件 test/Tests/Writers/AsciiDoc.hs。其中asciidoc unpack . purely (writeAsciiDocLegacy def) . toPandoc asciidoctor unpack . purely (writeAsciiDoc def) . toPandocasciidoc走writeAsciiDocLegacy对应asciidoc_legacy格式面向asciidoc-pyasciidoctor走writeAsciiDoc对应现代asciidoc格式面向 Asciidoctor。这与 MANUAL.txt 对输出格式的划分一致asciidoc是 Asciidoctor 解释的现代 AsciiDocasciidoc_legacy是asciidoc-py解释的旧版而asciidoctor只是asciidoc的废弃别名。10105 用例使用的-t asciidoc即现代格式。4.2 相关源码文件速查关注点位置link:前缀判定与链接输出src/Text/Pandoc/Writers/AsciiDoc.hs换行模式对 SoftBreak 的影响src/Text/Pandoc/Writers/AsciiDoc.hsescapeURI与 IANA scheme 列表src/Text/Pandoc/URI.hs、src/Text/Pandoc/URI.hs--wrap选项说明MANUAL.txt命令行测试框架test/Tests/Command.hsAsciiDoc 写器单元测试test/Tests/Writers/AsciiDoc.hs五、实战小结与自查清单在实际使用pandoc -t asciidoc或-t asciidoctor输出链接时可以对照以下规则自查目标为http:/https:/ftp:/irc:/mailto:协议且是绝对 URL输出隐式链接宏URL[text]不加前缀目标是相对路径如downloads/foo.zipparseURI解析失败输出link:downloads/foo.zip[text]目标为其他协议如ftps:、ssh:、doi:等虽然可能是合法 IANA scheme但不在写器豁免列表内输出link:URL[text]mailto:链接且文本等于地址本身输出裸文本由 AsciiDoc 自动识别为邮件链接链接目标含--退化为link:...[...]pass-through 写法。通过 test/command/10105.md 这个短小精悍的回归用例我们可以一眼看穿 pandoc AsciiDoc 写器在链接宏选择上的设计取舍对常用协议追求简洁的隐式宏对非常用协议和相对路径则退回显式link:宏从而兼顾输出可读性与渲染可靠性。当你在自己的文档转换流程中遇到link:前缀意外出现时不妨回到这份豁免列表判断目标协议是否属于那五个白名单协议即可。【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考