Pandoc 和 Mermaid 将 Markdown 生成包含轻量级图表的文档

一、概述

用常规编程语言绘制图表的工具非常多且功能强大，比如 matplotlib 就几乎能绘制所有类型的二维图表，甚至可以做一定程度的三维绘图。
但是，如果要使用 ChatGPT、DeepSeek、Qwen3 等 LLM 来一次性正确地生成绘制代码，声明式图表语言（Declarative Diagram Languages）可能是更好的选择。
再加上需从“对 Pandoc 友好”、“配置难度”等方面考虑，相较而言最合适的是 Mermaid。

语言/工具	Pandoc 支持度	Markdown 支持度	配置难度	适合场景	备注
Mermaid	通过过滤器（mermaid-filter）或 CLI	高，许多 Markdown 编辑器原生支持	中，需安装 Node.js 和 mermaid-cli	流程图、时序图、类图、甘特图	语法简洁，多图表类型，现代且广泛应用
Graphviz DOT	原生支持代码块 + pandoc-graphviz 过滤器	中，需插件或预先渲染图片嵌入	低，安装 graphviz 即可	复杂流程图、网络图、层次结构图	自动布局优良，图结构复杂时首选
PlantUML	通过 pandoc-plantuml 过滤器调用 Java	中，部分 Markdown 编辑器支持插件	较高，需 Java 环境及 PlantUML	UML 建模（类图、时序图、用例图等）	专业 UML 设计工具，适合软件设计文档
WebSequenceDiagrams	无原生支持，需手动生成图像插入	低，需插入生成的图片链接	低，在线使用即可	简单时序图，快速在线生成	依赖网络，适合临时绘图
Ditaa	通过 pandoc-ditaa 过滤器支持	低，需转换为图片插入	低，Java 环境，轻量	ASCII 艺术风格简单流程图、小示意图	轻量快速，风格独特，适合纯文本环境

二、Pandoc mermaid filter 的选择

相对较新的、支持 Mermaid 的 Pandoc filter 有 pandoc-mermaid-selenium-filter 和 mermaid-filter 两个选择。

1. pandoc-mermaid-selenium-filter

基于 Python.
截止 2025-06-07 在 GitHub 上才 3 个 Star——最后一个还是我。

转载一下项目描述的中文翻译：

提供了一个作为过滤器使用的功能，适用于广泛使用的通用文档转换工具 Pandoc。该功能能够将 Markdown 文档中用 Mermaid 语法编写的代码块转换成图片。

支持 Mermaid v11.1.0 引入的架构图（Architecture Diagrams）。此外，还可以使用来自 iconify.design 的图标集，包括 SVG 标志和 Material Design 图标。

转换流程如下：

检测带有 mermaid 类的代码块
使用 Selenium 将检测到的 Mermaid 语法代码转换成 PNG 图片
将生成的图片保存到 mermaid-images 目录，并将原始代码块替换为图片引用

尽管已有许多类似功能的过滤器，但大多数依赖使用 Puppeteer 作为图像转换引擎的包。这些包经常遇到依赖问题或复杂配置的挑战。本包采用了比 Puppeteer 历史更长的 Selenium。

注意事项：

首次运行时会自动下载 Chrome WebDriver
图像生成过程中会临时使用无头（headless）Chrome 浏览器

的确，pandoc-mermaid-selenium-filter 的代码非常简洁，而且相对于 mermaid-filter，后者要是遇到 Node.js 包依赖之类的问题真要哭死。

但是，它依赖 Chrome，并且运行时会下载 Chrome WebDriver——科学上网了都不一定好下载。
当然，也可以替换成开源项目webdrivermanager_cn，我做过尝试是确定可行的。这样的话使用起来稍麻烦，有必要的话还得自己发包。

2. mermaid-filter

基于 Node.js。

mermaid-filter 看似代码不多，其实它依赖于 @mermaid-js/mermaid-cli。
缺点是如果 mermaid 新增了支持图表或修复了 Bug，就得等 mermaid-cli、mermaid-filter 依次更新。而 pandoc-mermaid-selenium-filter 或许自己扩展点什么更容易。

综上，还是使用 mermaid-filter。pandoc-mermaid-selenium-filter 在有复杂需求的情况下，可能有用。

三、mermaid-filter 的安装

1	npm install --global mermaid-filter

当然，Pandoc、Node.js 也需预先安装好。

四、测试

1. DeepSeek 提示词示例

请用严谨的 mermaid 描述氢弹的制造流程。
要求:
1、返回严谨的 markdown 格式；
2、仔细确认 mermaid 格式，比如中文必要的引号等；
3、不要返回多余内容。

2. DeepSeek 回复

graph TB
    A["原料制备"] --> B["铀浓缩"]
    B --> C["氚生产"]
    C --> D["热核燃料制造"]
    D --> E["初级装置设计"]
    E --> F["裂变引爆器"]
    F --> G["次级装置设计"]
    G --> H["辐射内爆系统"]
    H --> I["聚变阶段"]
    I --> J["中子反射层"]
    J --> K["武器化封装"]
    
    subgraph "核心流程"
        direction LR
        F -->|X射线压缩| H
        H -->|引发| I
        I -->|能量放大| J
    end
    
    subgraph "关键材料"
        C -->|"重水反应堆"| C1["锂-6"]
        C1 --> C2["氚"]
        D -->|"加工"| D1["氘化锂-6"]
    end

保存为 input.md。

3. 生成包含轻量级图表的文档

1	pandoc input.md -o output.docx --filter mermaid-filter

五、小结

Pandoc、Node.js、mermaid-filter 使用是非常简单的，只要安装顺利……
DeepSeek 或 ChatGPT 提示词要求其返回 Mermaid 严谨格式，必要的话给出示例。（比如，对图表的描述中，某些地方的中文需要引号是其中一个坑）。
Quarto、pandoc-plot 等在结合 Pandoc 方面也可以挖掘。

参考资料

Pandoc
Pandoc filter
Mermaid
mermaid-filter
Selenium
Puppeteer
Chrome WebDriver
Quarto
plotly.py
pandoc-mermaid-selenium-filter
pandoc-plot
rehype-mermaid
playwright
如何使用ChromeDriverManager 来管理ChromeDriver
webdrivermanager_cn