Pandoc LaTeX 图片环境转换指南figure 与 subfigure 到 HTML5 的完整链路【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc导读本文以仓库中的命令测试用例 test/command/3577.md 为主体深入讲解 Pandoc 如何将 LaTeX 的figure、subfigure图片环境含\caption、\label、[ht]等放置参数转换为 HTML5 的嵌套figure/figcaption结构并给出可复现的命令、逐行输出解析与底层源码原理。读完本文你将掌握 LaTeX 文档中的单图、子图subfloat场景迁移到 HTML5 时的完整行为以及如何利用data-latex-placement属性做进一步的页面布局控制。一、测试场景总览3577 号用例在验证什么test/command/3577.md是 Pandoc 命令测试套件test/Command.hs中的一个用例文件内以标准格式记录了“输入命令 输入内容以^D结束的 stdin 期望输出”。它包含两个子场景场景输入关注点场景一一个外层figure内嵌两个subfigure每个子图各有\includegraphics与\caption外层另有总\caption嵌套figure的层级、两个子图题注 总题注的映射关系场景二一个普通figure含单张图片与\caption基础figure环境的转换、data-latex-placement属性这个用例的核心目标是确保 LaTeX 中“图中有子图”的经典排版subcaption 宏包风格在转成 HTML5 后语义结构依然完整保留外层一个figure承载总题注内层每个subfigure各自成为独立的figure并携带自己的题注。二、完整转换示例与逐行解析2.1 场景一包含 subfigure 的嵌套 figure输入命令与 LaTeX 内容如下% pandoc -f latex -t html5 --quiet \begin{figure}[ht] \begin{subfigure}{0.45\textwidth} \centering \includegraphics{img1.jpg} \caption{Caption 1} \end{subfigure} \begin{subfigure}{0.45\textwidth} \centering \includegraphics{img2.jpg} \caption{Caption 2} \end{subfigure} \caption{Subfigure with Subfloat} \end{figure}Pandoc 输出已与测试期望比对figure>% pandoc -f latex -t html5 \begin{figure}[ht] \includegraphics{img1.jpg} \caption{Caption 3} \end{figure}输出figure>pandoc -f latex -t html5 --quiet EOF \begin{figure}[ht] \includegraphics{img1.jpg} \caption{Caption 3} \end{figure} EOF-f latex指定输入格式为 LaTeX-t html5指定输出格式为 HTML5输出figure/figcaption语义标签--quiet抑制警告信息保证输出干净便于与期望结果做 diff。方式二文件输入pandoc input.tex -t html5测试期望输出分别保存在 test/command/3577.md 的代码块中整个命令测试套件通过 test-pandoc.hs 驱动运行核心断言逻辑可参考 test/Command.hs。四、源码级原理LaTeX 读取器如何解析 figure/subfigure4.1 环境注册在 LaTeX 读取器 src/Text/Pandoc/Readers/LaTeX.hs 中三个环境被统一注册到解析表(figure, env figure figure) (figure*, env figure* figure) (subfigure, env subfigure $ skipopts * tok * figure)figure与figure*直接交给解析函数figurefigure*是双栏排版中跨栏的通栏图环境subfigure稍有不同skipopts先跳过可选的[位置]参数tok再消费掉{0.45\textwidth}这样的宽度参数然后才进入与普通figure相同的figure解析逻辑——这正是子图能被解析成“独立 figure 块”的原因。4.2 figure 的解析流程核心解析函数位于 src/Text/Pandoc/Readers/LaTeX.hs关键步骤figure try $ do sp poshint - option $ untokenize $ bracketedToks -- 捕获 [ht] 放置参数 sp resetCaption -- 重置题注收集器 innerContent - many $ try (Left $ label) | (Right $ block) ... let kvs [(latex-placement, poshint) | not (T.null poshint)] let ident fromMaybe mblabel let attr (ident, [], kvs) ... return $ B.figureWith attr caption content对应关系[ht]放置参数通过bracketedToks读取环境开头的方括号内容存入poshint随后以键值对(latex-placement, poshint)写入图块的属性。这就是输出中data-latex-placementht的来源。resetCaption在进入环境体之前重置题注状态保证之后遇到的\caption能被正确归属。\label处理环境内出现的\label{...}会被单独捕获成为图块的标识符ident同时读取器会为带标签的图维护编号getNextNumber sLastFigureNum使后续\ref能解析出正确的图号以点分编号如1.1形式存储于sLabels。构建 Figure 块最终通过B.figureWith attr caption content构造出 Pandoc 的Figure块属性中携带标识符、空 class 和latex-placement键值对。另外figure内的辅助函数go专门处理图片占位文本go (Para [Image attr [Str image] target]) Plain [Image attr [] target]即把\includegraphics转换出的“图片 隐式 altimage”简化为空 alt 的图片因为真正的题注文本已被提升到Figure的 caption 上。这解释了输出中img srcimg1.jpg /为什么没有 alt 属性。五、中间表示与 HTML 写入器渲染5.1 统一的 Figure 块无论输入是figure、figure*还是subfigureLaTeX 读取器最终都产出同一个Figure块。在 HTML 写入器 src/Text/Pandoc/Writers/HTML.hs 中blockToHtmlInner opts (Figure attrs (Caption _ captBody) body) do html5 - gets stHtml5 ... let figCaption if html5 then [ H5.figcaption ! fcattr $ captCont ] -- HTML5: figcaption else [ (H.div ! A.class_ figcaption) captCont ] -- HTML4: div.figcaption ... if html5 then foldl (!) H5.figure figAttrs innards -- HTML5: figure else foldl (!) H.div (A.class_ float : figAttrs) innards -- HTML4: div.float由此可以明确HTML5 输出使用figurefigcaptionHTML4 输出则退化为div.floatdiv.figcaption图块属性attrs全部经attrsToHtml渲染未识别的键如latex-placement按 Pandoc 规则输出为data-*自定义属性因此latex-placement变成了data-latex-placement题注位置可通过写入选项writerFigureCaptionPosition命令行对应--figure-caption-positionabove|below控制CaptionBelow时图片在前、题注在后即默认的测试输出形态CaptionAbove时两者互换。5.2 嵌套结构的形成因为内层subfigure被解析为独立的Figure块它们作为外层Figure的body内容被blockListToHtml逐一渲染自然形成了“外层figure内嵌套两个figure”的 DOM 层级而外层Figure的 caption 是总题注渲染为最外层的figcaption与测试期望完全一致。六、延伸场景与注意事项双栏通栏图使用\begin{figure*}时读取器走完全相同的figure逻辑见 src/Text/Pandoc/Readers/LaTeX.hs因此也能得到同样的figure contenteditable="false">【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Pandoc LaTeX 图片环境转换指南：figure 与 subfigure 到 HTML5 的完整链路
Pandoc LaTeX 图片环境转换指南figure 与 subfigure 到 HTML5 的完整链路【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc导读本文以仓库中的命令测试用例 test/command/3577.md 为主体深入讲解 Pandoc 如何将 LaTeX 的figure、subfigure图片环境含\caption、\label、[ht]等放置参数转换为 HTML5 的嵌套figure/figcaption结构并给出可复现的命令、逐行输出解析与底层源码原理。读完本文你将掌握 LaTeX 文档中的单图、子图subfloat场景迁移到 HTML5 时的完整行为以及如何利用data-latex-placement属性做进一步的页面布局控制。一、测试场景总览3577 号用例在验证什么test/command/3577.md是 Pandoc 命令测试套件test/Command.hs中的一个用例文件内以标准格式记录了“输入命令 输入内容以^D结束的 stdin 期望输出”。它包含两个子场景场景输入关注点场景一一个外层figure内嵌两个subfigure每个子图各有\includegraphics与\caption外层另有总\caption嵌套figure的层级、两个子图题注 总题注的映射关系场景二一个普通figure含单张图片与\caption基础figure环境的转换、data-latex-placement属性这个用例的核心目标是确保 LaTeX 中“图中有子图”的经典排版subcaption 宏包风格在转成 HTML5 后语义结构依然完整保留外层一个figure承载总题注内层每个subfigure各自成为独立的figure并携带自己的题注。二、完整转换示例与逐行解析2.1 场景一包含 subfigure 的嵌套 figure输入命令与 LaTeX 内容如下% pandoc -f latex -t html5 --quiet \begin{figure}[ht] \begin{subfigure}{0.45\textwidth} \centering \includegraphics{img1.jpg} \caption{Caption 1} \end{subfigure} \begin{subfigure}{0.45\textwidth} \centering \includegraphics{img2.jpg} \caption{Caption 2} \end{subfigure} \caption{Subfigure with Subfloat} \end{figure}Pandoc 输出已与测试期望比对figure>% pandoc -f latex -t html5 \begin{figure}[ht] \includegraphics{img1.jpg} \caption{Caption 3} \end{figure}输出figure>pandoc -f latex -t html5 --quiet EOF \begin{figure}[ht] \includegraphics{img1.jpg} \caption{Caption 3} \end{figure} EOF-f latex指定输入格式为 LaTeX-t html5指定输出格式为 HTML5输出figure/figcaption语义标签--quiet抑制警告信息保证输出干净便于与期望结果做 diff。方式二文件输入pandoc input.tex -t html5测试期望输出分别保存在 test/command/3577.md 的代码块中整个命令测试套件通过 test-pandoc.hs 驱动运行核心断言逻辑可参考 test/Command.hs。四、源码级原理LaTeX 读取器如何解析 figure/subfigure4.1 环境注册在 LaTeX 读取器 src/Text/Pandoc/Readers/LaTeX.hs 中三个环境被统一注册到解析表(figure, env figure figure) (figure*, env figure* figure) (subfigure, env subfigure $ skipopts * tok * figure)figure与figure*直接交给解析函数figurefigure*是双栏排版中跨栏的通栏图环境subfigure稍有不同skipopts先跳过可选的[位置]参数tok再消费掉{0.45\textwidth}这样的宽度参数然后才进入与普通figure相同的figure解析逻辑——这正是子图能被解析成“独立 figure 块”的原因。4.2 figure 的解析流程核心解析函数位于 src/Text/Pandoc/Readers/LaTeX.hs关键步骤figure try $ do sp poshint - option $ untokenize $ bracketedToks -- 捕获 [ht] 放置参数 sp resetCaption -- 重置题注收集器 innerContent - many $ try (Left $ label) | (Right $ block) ... let kvs [(latex-placement, poshint) | not (T.null poshint)] let ident fromMaybe mblabel let attr (ident, [], kvs) ... return $ B.figureWith attr caption content对应关系[ht]放置参数通过bracketedToks读取环境开头的方括号内容存入poshint随后以键值对(latex-placement, poshint)写入图块的属性。这就是输出中data-latex-placementht的来源。resetCaption在进入环境体之前重置题注状态保证之后遇到的\caption能被正确归属。\label处理环境内出现的\label{...}会被单独捕获成为图块的标识符ident同时读取器会为带标签的图维护编号getNextNumber sLastFigureNum使后续\ref能解析出正确的图号以点分编号如1.1形式存储于sLabels。构建 Figure 块最终通过B.figureWith attr caption content构造出 Pandoc 的Figure块属性中携带标识符、空 class 和latex-placement键值对。另外figure内的辅助函数go专门处理图片占位文本go (Para [Image attr [Str image] target]) Plain [Image attr [] target]即把\includegraphics转换出的“图片 隐式 altimage”简化为空 alt 的图片因为真正的题注文本已被提升到Figure的 caption 上。这解释了输出中img srcimg1.jpg /为什么没有 alt 属性。五、中间表示与 HTML 写入器渲染5.1 统一的 Figure 块无论输入是figure、figure*还是subfigureLaTeX 读取器最终都产出同一个Figure块。在 HTML 写入器 src/Text/Pandoc/Writers/HTML.hs 中blockToHtmlInner opts (Figure attrs (Caption _ captBody) body) do html5 - gets stHtml5 ... let figCaption if html5 then [ H5.figcaption ! fcattr $ captCont ] -- HTML5: figcaption else [ (H.div ! A.class_ figcaption) captCont ] -- HTML4: div.figcaption ... if html5 then foldl (!) H5.figure figAttrs innards -- HTML5: figure else foldl (!) H.div (A.class_ float : figAttrs) innards -- HTML4: div.float由此可以明确HTML5 输出使用figurefigcaptionHTML4 输出则退化为div.floatdiv.figcaption图块属性attrs全部经attrsToHtml渲染未识别的键如latex-placement按 Pandoc 规则输出为data-*自定义属性因此latex-placement变成了data-latex-placement题注位置可通过写入选项writerFigureCaptionPosition命令行对应--figure-caption-positionabove|below控制CaptionBelow时图片在前、题注在后即默认的测试输出形态CaptionAbove时两者互换。5.2 嵌套结构的形成因为内层subfigure被解析为独立的Figure块它们作为外层Figure的body内容被blockListToHtml逐一渲染自然形成了“外层figure内嵌套两个figure”的 DOM 层级而外层Figure的 caption 是总题注渲染为最外层的figcaption与测试期望完全一致。六、延伸场景与注意事项双栏通栏图使用\begin{figure*}时读取器走完全相同的figure逻辑见 src/Text/Pandoc/Readers/LaTeX.hs因此也能得到同样的figure contenteditable="false">【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考