mermaid-to-image

技能：将 Mermaid 转换为图像

将 Markdown（或其他文本）文件中的 ```mermaid 代码块转换为 PNG 图像，并用图像引用替换代码块。适用于不原生渲染 Mermaid 的平台（GitHub Pages/Jekyll、Dev.to 等）。

---

适用场景

• 用户要求将文件中的 Mermaid 图表转换为图像
• 用户想将指定的 Mermaid 代码块渲染为 PNG
• 发布工作流要求使用静态图像而非 Mermaid 代码块

---

工作流

步骤 1：确定目标文件

用户可能会指定：

• 单个文件：convert mermaid blocks in docs/architecture.md
• 多个文件：convert mermaid in all files under docs/
• 特定代码块：convert the second mermaid block in README.md

扫描目标文件中的 ```mermaid 代码块。在继续之前，报告找到的代码块数量及其所在文件。

步骤 2：确定图像输出目录

检查项目结构，确定通常存放图像的位置：

# Look for common image directories
ls -d images/ img/ assets/ assets/images/ static/images/ docs/images/ 2>/dev/null

如果存在明确的图像目录（例如 images/、assets/images/），请使用该目录。必要时按主题创建子目录（例如 images/<topic>/）。

如果没有明显的图像目录，或存在多个候选目录，请询问用户：

Where should I save the rendered Mermaid images?

1. images/ (create new)
2. assets/images/
3. docs/figures/
4. Custom — enter a path

步骤 3：将每个图表渲染为 PNG

使用 mermaid.ink API 渲染图表。对每个代码块运行以下 Python 代码片段：

import base64, urllib.request

def render_mermaid(code: str, output_path: str):
    """Render a Mermaid diagram to PNG via mermaid.ink API."""
    encoded = base64.urlsafe_b64encode(code.encode()).decode()
    url = f"https://mermaid.ink/img/{encoded}?bgColor=white"
    req = urllib.request.Request(url, headers={"User-Agent": "Mozilla/5.0"})
    resp = urllib.request.urlopen(req, timeout=30)
    with open(output_path, "wb") as f:
        f.write(resp.read())

**重要：**必须设置 User-Agent 标头——如果没有该标头，mermaid.ink 会返回 403。

命名约定

根据图表内容使用描述性文件名，而不要使用通用名称：

• 推荐：architecture-overview.png、data-flow.png、heartbeat-sequence.png
• 不推荐：mermaid-1.png、diagram.png、image1.png

步骤 4：用图像引用替换代码块

将每个 ```mermaid ... ``` 代码块替换为 Markdown 图像引用，并使用从文件到图像的相对路径：

![Architecture overview](images/topic/architecture-overview.png)

如果项目使用绝对 URL（例如 GitHub Pages），则使用绝对 URL：

![Architecture overview](https://example.github.io/images/topic/architecture-overview.png)

选择与项目现有图像引用相符的链接形式。如果不确定，请使用相对路径。

步骤 5：报告结果

处理完成后，汇总以下信息：

• 转换了多少个图表
• 图像保存在哪里
• 修改了哪些文件

---

边缘情况

• 大型图表：mermaid.ink 可能会在处理非常复杂的图表时超时。如果渲染失败，请报告错误，并建议用户简化图表或尝试其他渲染器。
• 单个文件中有多个代码块：按顺序处理所有代码块，并为每个代码块指定唯一且具有描述性的文件名。
• 已渲染的代码块：如果 Mermaid 代码块已有对应图像（已注释或位于相邻位置），请跳过该代码块或询问用户。
• 非 Markdown 文件：同样的方法适用于包含 Mermaid 代码块的任何文本文件（例如 .rst、.txt）。