如何在Markdown文档中嵌入Mermaid图并配合Doxygen使用？

如何让Doxygen生成包含嵌入在GitHub Markdown文件（*.md）中的Mermaid图的内容？

我希望无需创建独立的Mermaid图文件并从Markdown文档引用，能像PlantUML与Doxygen配合那样使用Mermaid。PlantUML在Doxygen中表现出色，而Mermaid的优势在于，当Markdown文档在GitLab、VS Code的Markdown预览中查看时，它能在浏览器端渲染（Azure DevOps Git暂不支持此功能）。

但和PlantUML相比，Mermaid的劣势是Doxygen无法从包含它的Markdown文件中生成对应的图，我认为这可能是因为Mermaid采用浏览器端渲染方式导致的。求Mermaid与Doxygen配合使用的技巧。

技巧一：用自定义过滤器将Mermaid转为图片（兼容Doxygen静态输出） #

这种方法能让Doxygen把Markdown里的Mermaid代码块转换成静态图片，同时保留原始Mermaid代码不影响其他平台预览：

1. 安装Mermaid命令行工具：

   npm install -g @mermaid-js/mermaid-cli
   

2. 编写Python过滤脚本（比如mermaid-filter.py），用于识别Markdown中的Mermaid代码块并生成图片：

   import sys
   import os
   import subprocess
   import uuid
   
   in_mermaid = False
   mermaid_code = []
   
   for line in sys.stdin:
       stripped_line = line.strip()
       if stripped_line == "```mermaid":
           in_mermaid = True
           continue
       if stripped_line == "```" and in_mermaid:
           # 生成唯一文件名避免冲突
           img_filename = f"mermaid_{uuid.uuid4().hex}.svg"
           output_dir = os.environ.get("DOXYGEN_OUTPUT_DIR", os.getcwd())
           img_path = os.path.join(output_dir, img_filename)
           temp_mmd = f"/tmp/mermaid_{uuid.uuid4().hex}.mmd"
   
           # 写入临时Mermaid文件
           with open(temp_mmd, "w") as f:
               f.write("\n".join(mermaid_code))
           # 调用mmdc生成图片
           subprocess.run(["mmdc", "-i", temp_mmd, "-o", img_path], check=True)
           # 输出Doxygen可识别的图片引用
           print(f"![Mermaid 图]({img_filename})")
           # 清理临时文件
           os.remove(temp_mmd)
           in_mermaid = False
           mermaid_code = []
           continue
       if in_mermaid:
           mermaid_code.append(stripped_line)
       else:
           print(line, end="")
   

3. 修改Doxygen配置文件（Doxyfile）：

   # 指定Markdown文件使用自定义过滤器
   FILTER_PATTERNS        = *.md=mermaid-filter.py
   # 确保脚本有执行权限
   FILTER_SOURCE_FILES    = YES
   

   这样Doxygen处理Markdown时会自动将Mermaid代码转为图片，原始Markdown中的Mermaid代码块依然保留，不影响GitLab、VS Code等平台的预览渲染。

技巧二：给Doxygen生成的HTML注入Mermaid渲染脚本（浏览器端动态渲染） #

这种方法无需生成静态图片，让Doxygen的HTML页面直接加载Mermaid库渲染图：

1. 下载Mermaid的压缩JS文件（比如mermaid.min.js），放到Doxygen的工作目录。
2. 创建自定义HTML头部文件custom_header.html，添加Mermaid加载脚本：

   <script src="mermaid.min.js"></script>
   <script>
       // 初始化Mermaid，自动渲染页面中的Mermaid代码块
       document.addEventListener('DOMContentLoaded', function() {
           mermaid.initialize({ startOnLoad: true });
           // 给所有Mermaid代码块添加mermaid类，触发渲染
           document.querySelectorAll('pre code.language-mermaid').forEach(block => {
               const pre = block.parentElement;
               pre.className = 'mermaid';
               // 替换原始代码块内容为纯文本（避免代码高亮冲突）
               pre.innerHTML = block.textContent;
           });
       });
   </script>
   

3. 修改Doxyfile配置：

   # 引入自定义头部和Mermaid JS文件
   HTML_HEADER            = custom_header.html
   HTML_EXTRA_FILES       = mermaid.min.js
   

   这样Doxygen生成的HTML页面会自动渲染所有Mermaid图，同时原始Markdown在其他平台的预览不受影响。

内容的提问来源于stack exchange，提问作者Ed of the Mountain