如何配置Pandoc将带标签的LaTeX公式正确转换为Sphinx适配的RST格式

解决方案 #

你可以用pandoc-crossref过滤器处理LaTeX到reStructuredText转换过程中的公式标签与引用问题，这是目前最成熟的跨格式交叉引用处理方案，操作步骤如下：

• 第一步：安装pandoc-crossref，需保证其版本与你本地安装的Pandoc版本完全匹配，可通过pip、conda、scoop等包管理器直接安装，也可下载对应版本的预编译二进制文件使用。
• 第二步：执行转换命令时添加过滤器参数，示例命令如下：

pandoc 输入文件.tex -o 输出文件.rst --filter pandoc-crossref

执行上述命令后，你给出的测试用例转换结果将完全匹配你期望的输出格式：公式的\label会自动转为.. math::指令的:label:参数，\ref引用会自动转为:eq:角色的引用格式。

如果不想依赖额外工具，也可以自行编写简单的Pandoc Lua过滤器实现对应逻辑，核心逻辑是遍历AST中的数学块提取\label内容放到指令参数中，同时将引用链接替换为:eq:角色格式，示例过滤器代码如下：

-- 保存所有公式标签映射
local eq_labels = {}

-- 处理数学块，提取并移除\label，添加属性
function Math(m)
  if m.mathtype == 'DisplayMath' then
    local label = m.text:match('\\label%{(.-)%}')
    if label then
      eq_labels['#'..label] = label
      m.text = m.text:gsub('\\label%{.-%}%s*', '')
      m.attributes['label'] = label
    end
  end
  return m
end

-- 处理引用链接，替换为rst的eq角色格式
function Link(l)
  local target = l.target
  if eq_labels[target] then
    return pandoc.RawInline('rst', string.format(':eq:`%s`', eq_labels[target]))
  end
  return l
end

使用时将上述代码保存为eq-ref-filter.lua，转换时添加参数--lua-filter eq-ref-filter.lua即可。

内容的提问来源于stack exchange，提问作者Brian