mermaid-rasterize

name	mermaid-rasterize
description	Rasterize specific mermaid blocks inside a markdown file into PNG images. Use when mermaid diagrams don't render in the target viewer (GitHub, Notion, PDF, etc.). Triggers on: rasterize diagrams, mermaid isn't rendering, convert mermaid to images, replace mermaid blocks with images.

Mermaid Rasterize

Converts user-selected mermaid blocks into a PNG + .mmd source file, then rewrites only those blocks in the markdown with image references.

0. Resolve inputs from context — avoid redundant reads

Before reading any file, check what is already available in the conversation:

What to resolve	Check first	Fallback
Mermaid block content	Already in conversation? Use it directly	Read the markdown file
Which blocks to convert	User specified them? Proceed	List found blocks and ask
Markdown file path	Mentioned in conversation? Use it	Ask the user
Output/asset folder	Mentioned in conversation? Use it	Run detection (Step 2)

Only perform file reads for information that is genuinely missing. Never re-read content already visible in context.

1. Install mmdc

which mmdc || npm install -g @mermaid-js/mermaid-cli

On sandbox errors (Linux/CI), create once and reuse:

echo '{"args":["--no-sandbox","--disable-setuid-sandbox"]}' > /tmp/puppeteer.json

Append --puppeteerConfigFile /tmp/puppeteer.json to every mmdc call.

2. Detect asset folder (only if not already known)

ls $(dirname <file>) && ls $(dirname <file>)/..

Pick the first match:

1. assets/ exists → use it
2. images/ or img/ or static/ exists → use it
3. Other images already alongside the .md → use same folder
4. Nothing found → ask the user before continuing

3. Name each diagram

• contextname: markdown filename without extension, slugified (e.g. sistema-auth)
• diagramname: infer from diagram type or first node label; fallback to diagram-1, diagram-2

Output files per block:

<asset-folder>/diagram-{contextname}-{diagramname}.mmd   ← source
<asset-folder>/image-{contextname}-{diagramname}.png     ← rendered

4. Extract, save, and convert

For each confirmed block:

cat > <asset-folder>/diagram-{contextname}-{diagramname}.mmd << 'EOF'
<mermaid content>
EOF

mmdc \
  -i <asset-folder>/diagram-{contextname}-{diagramname}.mmd \
  -o <asset-folder>/image-{contextname}-{diagramname}.png \
  --scale 2 --backgroundColor white

5. Rewrite the markdown

Replace only the converted blocks with a relative image reference. Leave all other blocks untouched.

![{diagramname}]({asset-folder}/image-{contextname}-{diagramname}.png)

Save updated .md and generated files to /mnt/user-data/outputs/ mirroring the folder structure.

6. Present outputs

Call present_files with the updated .md first, then each .png. Tell the user which diagrams were converted and which were skipped.

---

Troubleshooting

Problem	Fix
Sandbox crash	Add --puppeteerConfigFile /tmp/puppeteer.json
mmdc not found	export PATH="$PATH:$(npm root -g)/.bin"
Blank PNG	Validate syntax at https://mermaid.live
Broken image links	Verify relative path from .md to asset folder