mermaid-to-image

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill: Mermaid to Image

技能：Mermaid转图片

Convert

```mermaid

code blocks in Markdown (or other text) files into PNG images, and replace the code blocks with image references. Useful for platforms that don't render Mermaid natively (GitHub Pages/Jekyll, Dev.to, etc.).

将Markdown（或其他文本）文件中的

```mermaid

代码块转换为PNG图片，并将代码块替换为图片引用。这对不原生支持Mermaid渲染的平台（如GitHub Pages/Jekyll、Dev.to等）非常有用。

When to Use

适用场景

The user asks to convert Mermaid diagrams in a file to images
The user wants to render specific Mermaid code blocks as PNG
A publishing workflow requires static images instead of Mermaid code blocks

用户要求将文件中的Mermaid图表转换为图片
用户希望将特定Mermaid代码块渲染为PNG
发布工作流需要静态图片而非Mermaid代码块

Workflow

工作流程

Step 1: Identify target files

步骤1：确定目标文件

The user may specify:

A single file:

convert mermaid blocks in docs/architecture.md

Multiple files:

convert mermaid in all files under docs/

A specific code block:

convert the second mermaid block in README.md

Scan the target file(s) for

```mermaid

code blocks. Report how many blocks were found and in which files before proceeding.

用户可能会指定：

单个文件：

convert mermaid blocks in docs/architecture.md

多个文件：

convert mermaid in all files under docs/

特定代码块：

convert the second mermaid block in README.md

扫描目标文件，查找

```mermaid

代码块。在开始处理前，报告找到的代码块数量以及所在文件。

Step 2: Determine the image output directory

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

Check the project structure to find where images are typically stored:

bash

undefined

检查项目结构，找到通常存储图片的目录：

bash

undefined

Look for common image directories

ls -d images/ img/ assets/ assets/images/ static/images/ docs/images/ 2>/dev/null


**If a clear image directory exists** (e.g., `images/`, `assets/images/`), use it. Create a subdirectory by topic if appropriate (e.g., `images/<topic>/`).

**If no image directory is obvious or multiple candidates exist**, ask the user:

Where should I save the rendered Mermaid images?

images/ (create new)
assets/images/
docs/figures/
Custom — enter a path

Tip: add "remember" to save this choice to CLAUDE.local.md.


If the user says "remember", save the choice to the project's `CLAUDE.local.md`:

```markdown

ls -d images/ img/ assets/ assets/images/ static/images/ docs/images/ 2>/dev/null


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

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

我应该将渲染后的Mermaid图片保存到哪里？

images/（新建）
assets/images/
docs/figures/
自定义 — 输入路径

提示：添加“remember”可将此选择保存到CLAUDE.local.md中。


如果用户回复“remember”，将选择保存到项目的`CLAUDE.local.md`文件中：

```markdown

Mermaid Image Output

Image directory:
```
<chosen-path>
```


On subsequent runs, check `CLAUDE.local.md` for a `## Mermaid Image Output` section and use it directly.

Image directory:
```
<chosen-path>
```


后续运行时，检查`CLAUDE.local.md`中的`## Mermaid Image Output`部分，并直接使用其中的设置。

Step 3: Render each diagram to PNG

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

Use the mermaid.ink API to render diagrams. Run this Python snippet for each block:

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())

Important: The

User-Agent

header is required — mermaid.ink returns 403 without it.

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

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错误。

Naming convention

命名规范

Use descriptive filenames based on the diagram content, not generic names:

GOOD:

architecture-overview.png

data-flow.png

heartbeat-sequence.png

BAD:
```
mermaid-1.png
```
,
```
diagram.png
```
,
```
image1.png
```

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

Step 4: Replace code blocks with image references

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

Replace each

```mermaid ... ```

block with a Markdown image reference using a relative path from the file to the image:

markdown

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

If the project uses absolute URLs (e.g., GitHub Pages), use those instead:

markdown

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

Choose the link style that matches the project's existing image references. If unsure, use relative paths.

使用文件到图片的相对路径，将每个

```mermaid ... ```

代码块替换为Markdown图片引用：

markdown

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

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

markdown

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

选择与项目现有图片引用一致的链接格式。如果不确定，使用相对路径。

Step 5: Report results

步骤5：报告结果

After processing, summarize:

How many diagrams were converted
Where the images were saved
Which files were modified

处理完成后，总结以下内容：

转换的图表数量
图片保存位置
修改的文件列表

Edge Cases

边缘情况

Large diagrams: mermaid.ink may time out on very complex diagrams. If a render fails, report the error and suggest the user simplify the diagram or try an alternative renderer.
Multiple blocks in one file: process all blocks in order, give each a unique descriptive filename.
Already-rendered blocks: if a mermaid block already has a corresponding image (commented out or adjacent), skip it or ask the user.
Non-Markdown files: the same approach works for any text file containing mermaid code blocks (e.g.,
```
.rst
```
,
```
.txt
```
).

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