企业官网建设流程全解析

Pandocimplicit_figures扩展深度解析：从 test/command/3450.md 看图片到图形的转换机制与禁用行为

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

导读

本文以 pandoc 官方命令测试用例 test/command/3450.md 为切入点，系统剖析implicit_figures扩展的完整行为：它如何在 Markdown 解析阶段把"单独成段且带非空替代文本的图片"提升为带标题的图形（figure），又如何在通过-fmarkdown-implicit_figures禁用该扩展后，将同样的图片语法降级为普通内联图片并正确传递尺寸属性到 HTML 与 LaTeX 输出。读完本文，你将理解该扩展在 reader 与 writer 两侧的实现位置、各类输出格式的渲染差异，以及如何在实际文档中精准控制"图片"与"图形"两种形态。

一、测试用例全貌：它在验证什么

pandoc 的命令测试体系以"输入 Markdown + 期望输出"的成对断言形式存在。test/command/3450.md包含两个独立断言，分别覆盖HTML 输出与LaTeX 输出两条转换链路，且统一采用-fmarkdown-implicit_figures语法——在 pandoc 中，-前缀表示禁用该扩展。

第一个断言（HTML 输出）：

% pandoc -fmarkdown-implicit_figures [![image](https://link.gitcode.com/i/54219c5eea72b86b8167a8faf3738c89)](https://link.gitcode.com/i/a3bc0a876dc76a1341c24dff84b2a665){height=2em} ^D <p><img src="lalune.jpg" style="height:2em" alt="image" /></p>

第二个断言（LaTeX 输出）：

% pandoc -fmarkdown-implicit_figures -t latex [![image](https://link.gitcode.com/i/54219c5eea72b86b8167a8faf3738c89)](https://link.gitcode.com/i/a3bc0a876dc76a1341c24dff84b2a665){height=2em} ^D \includegraphics[width=\linewidth,height=2em,keepaspectratio,alt={image}]{lalune.jpg}

输入行[![image](https://link.gitcode.com/i/54219c5eea72b86b8167a8faf3738c89)](https://link.gitcode.com/i/a3bc0a876dc76a1341c24dff84b2a665){height=2em}中，image是链接文本（即图片的 alt 文本），lalune.jpg是图片源文件（测试素材位于 test/command/lalune.jpg），{height=2em}是link_attributes语法中的显式图片属性。测试断言的核心结论是：禁用implicit_figures后，即使图片单独成段，它也不会被提升为图形，而是以普通内联图片输出，但height=2em等尺寸属性仍会逐格式地映射到目标语法的对应表达。

二、implicit_figures扩展的定义与默认启用情况

该扩展在源码中定义于 src/Text/Pandoc/Extensions.hs，其构造器注释直白地概括了语义："A paragraph with just an image is a figure"（一个只含图片的段落即图形）。

| Ext_implicit_figures -- ^ A paragraph with just an image is a figure

从同一文件的格式扩展集合可以看出它的默认启用边界：

• pandoc 默认的markdown扩展集包含Ext_implicit_figures（见pandocExtensions列表）；
• plainExtensions同样包含它（Extensions.hs）；
• MultiMarkdown（markdown_mmd）扩展集也启用它（Extensions.hs）；
• GitHub 风格 Markdown（markdown_github）与strict Markdown（markdown_strict）的扩展集（Extensions.hs 与 L350-L355）中均不包含它。

这意味着：如果你使用-fmarkdown_strict或-fmarkdown_github，行为与本测试用例一致（不会产生图形）；而默认的markdown格式则会触发图形化。因此-fmarkdown-implicit_figures的写法本质上是在默认 markdown 行为之上显式撤销该能力，属于验证"扩展开关生效"的经典命令测试模式——格式字符串中+/-前缀的扩展名会被getDefaultExtensions叠加或剔除。

三、启用时：reader 如何把独立图片提升为图形

implicit_figures的核心解析逻辑位于 Markdown reader 的段落解析函数para中，见 src/Text/Pandoc/Readers/Markdown.hs：

let figureOr constr inlns = case B.toList inlns of [Image attr figCaption (src, tit)] | extensionEnabled Ext_implicit_figures exts , not (null figCaption) -> do implicitFigure attr (B.fromList figCaption) src tit _ -> constr inlns

这段模式匹配揭示了两个必须同时满足的硬性条件：

1. 段落内联元素列表中恰好只有一个Image（[Image attr ...]），多一张图、混入文字都不行；
2. 该图片的 alt 文本（figCaption）非空（not (null figCaption)）。

两个条件都满足时才调用implicitFigure构造Figure块；否则回退为普通段落。这与官方手册 MANUAL.txt 的描述完全一致："An image with nonempty alt text, occurring by itself in a paragraph, will be rendered as a figure with a caption."（带非空 alt 文本且单独成段的图片将被渲染为带标题的图形，图片描述作为标题。）

implicitFigure的完整实现（Markdown.hs）还处理了属性分流：

implicitFigure :: Attr -> Inlines -> Text -> Text -> Blocks implicitFigure (ident, classes, attribs) capt url title = let alt = case "alt" `lookup` attribs of Just alt' -> B.text alt' _ -> capt attribs' = filter ((/= "latex-placement") . fst) (filter ((/= "alt") . fst) attribs) figattribs = case lookup "latex-placement" attribs of Just p -> [("latex-placement", p)] _ -> mempty ...

可以看到：显式的alt属性会覆盖 alt 文本；alt与latex-placement属性被从图片属性中剥离，其中latex-placement会被上移到 figure 自身的属性中，供 LaTeX writer 控制图形浮动位置使用。

CommonMark 变体 reader 也提供了对等支持：在 src/Text/Pandoc/Readers/CommonMark.hs 中，启用该扩展时会通过walk makeFigures对解析结果做后处理，把独立图片段落统一改写为图形。

四、禁用时：3450.md 中的两类输出如何产生

回到本测试用例：-fmarkdown-implicit_figures使上面figureOr的守卫条件不成立，[![image](https://link.gitcode.com/i/54219c5eea72b86b8167a8faf3738c89)](https://link.gitcode.com/i/a3bc0a876dc76a1341c24dff84b2a665){height=2em}始终保持为普通内联图片。此时输出形态完全由目标 writer 决定，这正是 3450.md 设计两个断言的原因。

4.1 HTML 输出：属性映射为内联样式

第一条断言期望输出：

<p><img src="lalune.jpg" style="height:2em" alt="image" /></p>

由于不是图形，图片被渲染为段落内的<img>标签：height=2em被映射为style="height:2em"，alt 文本image进入alt属性。作为对照，若未禁用该扩展，HTML writer 的blockToHtmlInner会走Figure分支（见 src/Text/Pandoc/Writers/HTML.hs），生成<figure>与<figcaption>结构而非裸<img>。因此 3450.md 的 HTML 断言实际验证的是：扩展开关关闭后，writer 不再进入 figure 渲染分支。

4.2 LaTeX 输出：尺寸属性的逐项映射

第二条断言期望输出：

\includegraphics[width=\linewidth,height=2em,keepaspectratio,alt={image}]{lalune.jpg}

这一行是 LaTeX writer 尺寸逻辑的浓缩体现，对应源码 src/Text/Pandoc/Writers/LaTeX.hs：

let showDim dir = ... optList = showDim Width <> showDim Height <> (case (dimension Height attr, dimension Width attr) of (Just _, Just _) -> [] _ -> ["keepaspectratio"]) <> maybe [] (\x -> ["alt=" <> braces (literal x)]) mbalt ...

结合输入{height=2em}逐项对照：

• height=2em→ 尺寸属性Height存在，映射为height=2em；
• width=\linewidth→ 用户未显式给出宽度，但源码中showDim Width在"未指定 Width 但 Height 已指定"时自动补充width=\linewidth（LaTeX.hs），保证图片按行宽约束显示；
• keepaspectratio→ 由于 Height 与 Width 只有一个被指定，源码中的(Just _, Just _) -> []分支不命中，于是追加keepaspectratio以在拉伸时保持宽高比；
• alt={image}→ 非 SVG 图片且存在 alt 文本时输出alt={...}（mbalt由lookup "alt" kvs或 stringify 后的描述生成）。

这正是测试 3450 的精妙之处：它锁定了 LaTeX writer 在"单维度尺寸"场景下的完整选项生成规则，任何对这些默认行为的改动都会导致断言失败。

五、周边测试与真实文档中的相关约束

implicit_figures是 pandoc 中被广泛测试的扩展，仓库内还有多个关联用例可佐证其行为边界，例如 test/command/6350.md（图片属性相关）、test/command/10755.md、test/command/8689.md 以及 test/command/typst-image-alt.md。这些用例共同覆盖了不同 writer 下的图片属性传播。

在实际写作中，以下来自 MANUAL.txt 的约束值得牢记：

• 并非所有输出格式都支持图形。手册明确指出部分格式（如 RTF）尚无 figure 概念，此时即便扩展启用，也只会输出"单独成段的图片"，标题会被丢弃。
• 想保留普通图片形态，只需确保图片不是段落中的唯一内容，例如在其后追加一个反斜杠硬换行（This image won't be a figure\）。
• 让 alt 文本与标题分离：借助link_attributes扩展（markdown 默认启用），显式写出The caption.{alt="description of image"}，此时alt属性作为无障碍替代文本，方括号内文本作为图形标题。
• LaTeX 浮动位置：为图形添加latex-placement属性（如{latex-placement=htbp}），reader 的implicitFigure会将其从图片属性上移到 figure 属性，供 LaTeX writer 生成\begin{figure}[htbp]。

Markdown writer 侧也存在对称逻辑（src/Text/Pandoc/Writers/Markdown.hs）：当文档中出现Figure块时，只有启用implicit_figures才把它还原为"带标题的独立图片段"，否则回退为 fenced div 或普通段落——这意味着往返转换（round-trip）时扩展开关是否一致，直接决定文档结构是否保真。

六、小结

test/command/3450.md用两个极简断言浓缩了implicit_figures扩展的开关语义：启用时，独立的非空 alt 图片在 reader 端被提升为Figure块（Readers/Markdown.hs）；禁用时，图片保持内联形态，但height等属性仍由各 writer 精确翻译——HTML 侧变为内联样式，LaTeX 侧则派生出width=\linewidth、keepaspectratio与alt={...}（Writers/LaTeX.hs）。理解这条链路，你就能在任何输出格式下准确预判"图片"与"图形"的最终形态，并在文档中灵活驾驭这一开关。

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