Skill: Mermaid to Image
Convert
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
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:
bash
# 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.,
,
), use it. Create a subdirectory by topic if appropriate (e.g.,
).
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
Tip: add "remember" to save this choice to CLAUDE.local.md.
If the user says "remember", save the choice to the project's
:
markdown
## Mermaid Image Output
- **Image directory**: `<chosen-path>`
On subsequent runs, check
for a
section and use it directly.
Step 3: Render each diagram to 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
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
- BAD: , ,
Step 4: Replace code blocks with image references
Replace each
block with a Markdown image reference using a
relative path from the file to the image:
markdown
If the project uses absolute URLs (e.g., GitHub Pages), use those instead:
markdown
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., , ).