Pandoc将LaTeX转HTML时忽略自定义LaTeX宏的求助

问题场景 #

我有一个包含自定义LaTeX宏\chapsummary的文件book.tex：

\begin{document}

\chapter{Chapter heading}

\chapsummary {
  \item Intro bullet 1
  \item Intro bullet 2
}

Some paragraph of text.

\end{document}

直接在book.tex开头定义宏时，执行pandoc book.tex -o book.html能正常转换出带列表的HTML。但想把宏定义放到单独文件中，无需修改原内容文件，之前尝试的两种方法都失败了：

• 方法1：用metadata.json
  创建metadata.json：

  {
    "header-includes": [
      "\\newcommand{\\chapsummary}[1]{ \\begin{itemize} \\#1 \\end{itemize}}",
    ]
  }
  

  执行pandoc --metadata-file=metadata.json -s book.tex -o book.html，宏未被解析，列表无法显示。
• 方法2：用--include-in-header引入commands.tex
  将宏定义放入commands.tex，执行pandoc --include-in-header=commands.tex book.tex -o book.html，宏定义被当作普通文本输出到HTML中，未生效。

错误原因 #

1. header-includes是用于向输出文档的头部添加内容（比如HTML的<head>、LaTeX的导言区内容），并非给Pandoc的LaTeX解析器提供宏定义，所以无法用来解析原LaTeX文件中的自定义宏。
2. --include-in-header参数的作用是将指定文件内容插入到输出HTML的<head>标签中，不会让Pandoc在解析LaTeX阶段加载宏定义，因此宏代码会被直接当作文本输出。

正确解决方案 #

方案1：将宏文件与原文件一同作为输入 #

1. 创建宏定义文件commands.tex：

\newcommand{\chapsummary}[1]{ \begin{itemize} #1 \end{itemize}}

2. 执行转换命令时，将宏文件和原文件一起传入Pandoc：

pandoc commands.tex book.tex -o book.html

Pandoc会按顺序解析输入文件，先加载commands.tex中的宏定义，再处理book.tex，就能正确识别并转换\chapsummary宏。

方案2：使用Pandoc的--include-before-body（针对LaTeX输入场景） #

如果不想在命令行中写多个文件名，可以用--include-before-body参数指定宏文件，这个参数会让Pandoc在解析主文档前先处理指定的LaTeX内容：

pandoc --include-before-body=commands.tex book.tex -o book.html

注意：此参数仅对LaTeX格式的输入生效，因为它是在解析主LaTeX文档前插入宏定义内容。

方案3：自定义Pandoc过滤器（复杂宏场景） #

如果后续宏逻辑复杂，上述简单方法无法满足需求，可以编写Pandoc过滤器（比如用Lua）来处理自定义宏。例如创建chapsummary-filter.lua：

function RawBlock(el)
  if el.format == "latex" and el.text:match("^\\chapsummary") then
    local content = el.text:gsub("^\\chapsummary%s*{(.-)}", "%1")
    local items = {}
    for item in content:gmatch("\\item%s*(.-)(?=\\item|$)") do
      table.insert(items, pandoc.ListItem(pandoc.Plain(pandoc.Str(item))))
    end
    return pandoc.BulletList(items)
  end
end

然后执行命令：

pandoc --lua-filter=chapsummary-filter.lua book.tex -o book.html

这种方式适合处理逻辑复杂的自定义宏，不受LaTeX语法限制。

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