含Mermaid图的Markdown转PDF时图表缺失问题求助

问题概述 #

将含Mermaid图的Markdown文档转换为PDF时，Markdown转HTML的过程完全正常，但尝试多种PDF生成方法（pandoc直接转、wkhtmltopdf、无头模式Microsoft Edge、Microsoft Office Word、“Microsoft Print to PDF”）后，最终PDF中均无法显示Mermaid图表。

最小可复现Markdown示例 #

# Test Document

This is a test document with a Mermaid diagram.

```{.mermaid format=svg}
graph TD
    A[Start] --> B{Is it?}
    B -->|Yes| C[OK]
    C --> D[Rethink]
    D --> B
    B ---->|No| E[End]

End of document.

### 成功生成HTML的命令
```cmd
set "PATH=C:\Windows\System32\;C:\Users\%USERNAME%\AppData\Roaming\npm;C:\Program Files\nodejs;C:\Users\%USERNAME%\AppData\Local\Yarn\bin;C:\ProgramData\chocolatey\bin;C:\Program Files\MiKTeX\miktex\bin\x64\;C:\ProgramData\chocolatey\lib\rsvg-convert\tools"

pandoc -F "C:\Users\%USERNAME%\AppData\Local\Yarn\bin\mermaid-filter.cmd" --lua-filter=toc-placement.lua --standalone --css=pandoc-custom-css.css --template pandoc-html-template.html input.md -o output.html

可靠解决方法 #

方法1：优化wkhtmltopdf转换参数 #

若从已生成的HTML转PDF，需确保wkhtmltopdf能正常访问页面内的SVG资源，执行以下命令：

pandoc output.html -o output.pdf --pdf-engine=wkhtmltopdf --pdf-engine-opt=--enable-local-file-access --pdf-engine-opt=--no-stop-slow-scripts

参数说明：

• --enable-local-file-access：允许工具读取本地SVG文件或内联SVG资源
• --no-stop-slow-scripts：确保页面脚本执行完成，避免因渲染未完成导致图表缺失

方法2：直接用pandoc结合Mermaid-filter生成PDF #

跳过HTML中间步骤，让pandoc直接调用Mermaid渲染引擎完成图表渲染与PDF生成，命令如下：

pandoc -F mermaid-filter --pdf-engine=wkhtmltopdf input.md -o output.pdf

前提：已正确安装mermaid-filter和mermaid-cli，且相关工具路径已添加至系统环境变量。

方法3：强制Mermaid输出内联SVG #

修改mermaid-filter的配置，使其生成内联SVG而非外部引用文件。内联SVG无需额外资源加载，在各类PDF转换工具中兼容性更强，可通过调整filter参数指定format=svg并开启内联输出。

内容的提问来源于stack exchange，提问作者Foad S. Farimani