如何避免Pandoc转义字符？自定义Lua过滤器适配Docusaurus

需要将WikiJS格式的Markdown图片元素：

![](/src/guides/administrator-guide/media/button_dataset.png){height=0.8cm}

转换为Docusaurus支持的MDX格式：

<img src="/src/guides/administrator-guide/media/button_dataset.png" height="0.8cm" />

编写了以下Lua过滤器尝试转换：

function Image (elem)
    return '<img src="' .. img.src .. '"' .. 'height="' .. img.attributes.height .. '" />'
end

但Pandoc会自动转义<、>和"字符，输出结果如下，无法被Docusaurus正常渲染：

\<img
src=\"/src/guides/administrator-guide/media/button_dataset.png\"
/\>

想知道如何让Pandoc原样输出字符串不转义，是否有对应开启选项？

解决方法 #

1. 使用Raw元素输出原生HTML #

Pandoc的Lua过滤器不能直接返回字符串（会被当作普通文本转义），正确做法是返回RawInline（行内元素）或RawBlock（块级元素），指定格式为html，这样Pandoc会原样输出内容，不进行转义。

同时修正原过滤器中变量错误（原代码用了未定义的img，应改为函数参数elem），修正后的过滤器代码：

function Image (elem)
  -- 构建img标签内容
  local imgTag = string.format('<img src="%s" height="%s" />', elem.src, elem.attributes.height)
  -- 图片属于行内元素，返回RawInline；若需块级可改用RawBlock
  return pandoc.RawInline('html', imgTag)
end

2. 指定正确的输出格式 #

执行Pandoc转换时，需指定输出格式为markdown或mdx（Docusaurus支持MDX），确保过滤器生效：

# 输出为markdown格式
pandoc input.md -o output.md --lua-filter=your-filter.lua --to=markdown

# 若Pandoc版本支持，可直接输出mdx格式
pandoc input.md -o output.mdx --lua-filter=your-filter.lua --to=mdx

3. 可选：添加图片alt文本 #

如果需要保留图片的alt文本，可扩展过滤器代码：

function Image (elem)
  -- 将图片caption转为字符串作为alt文本
  local altText = pandoc.utils.stringify(elem.caption)
  local imgTag = string.format('<img src="%s" alt="%s" height="%s" />', elem.src, altText, elem.attributes.height)
  return pandoc.RawInline('html', imgTag)
end

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