mermaid-to-image

Skill: Mermaid to Image

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

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

Workflow

Step 1: Identify target files

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.

Step 2: Determine the image output directory

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

# 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?

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

Step 3: Render each diagram to PNG

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

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.

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

Replace each mermaid ... block with a Markdown image reference using a relative path from the file to the image:

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

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

![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.

Step 5: Report results

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