Pandoc中figure*环境转换问题解析与解决方案

在学术写作和文档排版中，LaTeX的figure环境常用于双栏布局中插入跨栏的宽幅图片。然而，当使用Pandoc进行格式转换时，开发者可能会遇到一个典型问题：figure环境中的图片标题（caption）无法正确保留。

问题现象

通过对比常规figure环境和figure*环境的转换结果，我们可以清晰地观察到差异：

1. 常规figure环境转换
   输入LaTeX代码：

   \begin{figure}
   \includegraphics[width=0.8\textwidth]{figure.png}
   \caption{This is a figure}
   \label{fig:fig1}
   \end{figure}
   

   转换后Markdown输出完整保留了标题和标签：

   ![This is a figure](figure.png){#fig:fig1 width="80%"}
   

2. figure*环境转换
   输入LaTeX代码：

   \begin{figure*}
   \includegraphics[width=0.8\textwidth]{figure.png}
   \caption{This is a figure}
   \label{fig:fig1}
   \end{figure*}
   

   转换后Markdown丢失了标题信息：

   ::: figure*
   ![image](figure.png){width="80%"}
   :::
   

技术背景

figure*是LaTeX在双栏模式（twocolumn）下的特殊环境，用于创建跨栏浮动体。Pandoc的LaTeX解析器需要特殊处理这类环境：

1. AST节点差异
   常规figure会被解析为Image节点并携带Caption属性，而figure*目前被处理为Div容器，内部的Caption未被正确提取。

2. 语义保留挑战
   格式转换工具需要在保持文档语义的同时处理排版特性。figure*的跨栏特性在单栏格式（如Word）中本应退化为普通figure，但标题信息仍需保留。

解决方案

对于遇到此问题的用户，可采用以下临时解决方案：

1. 预处理替换
   在转换前使用sed等工具将figure*替换为figure：

   sed 's/figure\*/figure/g' input.tex | pandoc -f latex -t docx
   

2. 自定义Lua过滤器
   编写Lua脚本处理figure*环境：

   function Div(el)
     if el.classes[1] == "figure*" then
       return pandoc.Div(pandoc.utils.stringify(el.content), "figure")
     end
   end
   

最佳实践建议

1. 跨格式写作原则
   当文档需要多格式输出时，建议优先使用标准figure环境，通过CSS或样式表控制最终呈现效果。

2. 版本适配策略
   该问题已在Pandoc开发版中修复，建议关注版本更新。对于稳定版用户，可采用上述变通方案。

3. 元数据验证流程
   建立转换后的质量检查步骤，特别验证浮动体的标题、编号等关键元素是否完整保留。

通过理解这一转换问题的本质，开发者可以更有效地在跨格式文档处理中保持内容完整性，确保学术交流的信息准确性不受技术转换影响。