mermaid-render

mermaid-render

Convert Mermaid .mmd source files (or .excalidraw JSON files) to hand-drawn style PNGs.

Browser surface

The .mmd → PNG flow drives excalidraw.com via BYOB MCP (mcp__byob__browser_*) — the user's real Chrome. The .excalidraw → PNG flow does not touch a browser at all.

The .mmd flow uses mcp__byob__browser_eval to extract scene JSON from localStorage. BYOB blocks browser_eval by default; set BYOB_ALLOW_EVAL=1 before invoking BYOB if you need this flow. The gate is documented in docs/features/byob-browser-control.md.

Dependencies (install once)

npm install -g @moona3k/excalidraw-export

This handles .excalidraw → PNG headlessly (pure Node, no browser, ~100ms/file, authentic roughjs hand-drawn aesthetic).

Input types

Workflow A: .excalidraw → PNG (no browser needed)

excalidraw-export <file.excalidraw> -o <output.png> --scale 2
file <output.png>   # verify: should show "PNG image data"

Workflow B: .mmd → PNG

Step 1: Read and validate the Mermaid source

cat <file.mmd>

Before proceeding, check for diagram topologies that produce bad renders:

If any of these patterns are present, fix the .mmd source FIRST:

• Restructure the diagram to avoid the problematic topology
• Consider whether a table slide would communicate the idea better than a diagram
• For comparison/overlap diagrams: use two columns with shared items highlighted, not a flowchart

Step 2: Open excalidraw.com

mcp__byob__browser_navigate(url="https://excalidraw.com", waitUntil="networkidle")
mcp__byob__browser_read(url="https://excalidraw.com", reuseTab=true, screens=1)

Wait for the app to load — you should see toolbar buttons including "More tools".

Step 3: Open the Mermaid import dialog

Click "More tools" (look for it in the IE list by name: "More tools"), which expands a menu:

mcp__byob__browser_click(tabId=<tab>, selector="byob:idx=<more_tools_idx>")
mcp__byob__browser_read(url="https://excalidraw.com", reuseTab=true, screens=1)
# Look for menuitem name: "Mermaid to Excalidraw"
mcp__byob__browser_click(tabId=<tab>, selector="byob:idx=<mermaid_idx>")
mcp__byob__browser_read(url="https://excalidraw.com", reuseTab=true, screens=1)
# Dialog opens with a textbox and an "Insert" button

Step 4: Paste the Mermaid content

Type into the dialog textbox (clear=true to replace existing content):

mcp__byob__browser_type(tabId=<tab>, selector="byob:idx=<textbox_idx>", text="<contents of file.mmd>", clear=true)

Step 5: Insert

mcp__byob__browser_click(tabId=<tab>, selector="byob:idx=<insert_button_idx>")
mcp__byob__browser_screenshot(tabId=<tab>, savePath="/tmp/excalidraw-canvas.png")  # verify diagram rendered

Step 6: Extract scene data from localStorage

Excalidraw auto-saves the scene to localStorage. Extract it directly — this is more reliable than triggering a file download. Requires BYOB_ALLOW_EVAL=1 in the agent's environment:

mcp__byob__browser_eval(tabId=<tab>, expression="localStorage.getItem('excalidraw')")

Save the returned string to disk. The eval result is a JSON-encoded string (double-encoded), so unwrap it:

import json

raw = open('/tmp/scene_raw.txt').read().strip()
elements = json.loads(json.loads(raw))   # unwrap the double encoding

excalidraw_doc = {
    "type": "excalidraw",
    "version": 2,
    "source": "https://excalidraw.com",
    "elements": elements,
    "appState": {"viewBackgroundColor": "#ffffff", "gridSize": None},
    "files": {}
}

with open('/tmp/output.excalidraw', 'w') as f:
    json.dump(excalidraw_doc, f)

Step 7: Render to PNG

excalidraw-export /tmp/output.excalidraw -o <final-output.png> --scale 2
file <final-output.png>

Step 8: Validate the rendered output

Read the PNG and check for visual quality problems. This is not optional — a PNG that exists but looks broken is worse than no PNG.

Use the Read tool on the output PNG (Claude is multimodal and can evaluate images). Check for:

• Spaghetti lines: edges crossing in a tangled mess → Go back to Step 1, restructure the .mmd
• Overlapping labels: text on top of edges or other text → Simplify node labels or reduce connections
• Cramped layout: nodes too close together, text truncated → Reduce node count or switch orientation (TB↔LR)
• Blank or nearly blank output: rendering failed silently → Check the .excalidraw elements array
• Unreadable at slide scale: diagram too detailed for a presentation slide → Split into multiple diagrams

If any check fails, do NOT proceed. Fix the source .mmd and re-render. A bad diagram undermines the entire slide.

Step 9: Close the Excalidraw tab

When done, close the tab so the user's Chrome isn't left with an extra tab open:

mcp__byob__browser_close_tab(tabId=<tab>)

Export dialog (optional — use for quick screenshot verification)

To preview the diagram before extracting scene data, use Cmd+Shift+E:

mcp__byob__browser_press_key(tabId=<tab>, key="Meta+Shift+E")
mcp__byob__browser_read(url="https://excalidraw.com", reuseTab=true, screens=1)
# Look for "Export to PNG", "Export to SVG", "Only selected" checkbox
# Uncheck "Only selected" to export the full canvas
mcp__byob__browser_click(tabId=<tab>, selector="byob:idx=<export_png_idx>")

Note: the PNG download goes to the user's Downloads folder. Use this for visual verification only — the localStorage extraction (Step 6) is the correct path for saving the file.

Batch rendering

For multiple .mmd files, process sequentially. Clear the canvas between diagrams:

mcp__byob__browser_press_key(tabId=<tab>, key="Meta+a")          # select all
mcp__byob__browser_press_key(tabId=<tab>, key="Backspace")       # delete

Then repeat Steps 3–7 for the next file. The localStorage key excalidraw always holds the current canvas state.

Output naming convention

Troubleshooting

mcp__byob__browser_eval returns "browser_eval is disabled": BYOB blocks browser_eval by default. Set BYOB_ALLOW_EVAL=1 in the agent's environment and restart the BYOB MCP server (cd ~/.byob && bun run doctor).

BYOB transport error: Run cd ~/.byob && bun run doctor to confirm the extension is loaded and the native bridge is running. If red, re-run the machine's BYOB install/opt-in flow (in repos with a setup skill, that flow handles it; otherwise reinstall under ~/.byob and re-run bun run doctor).

"More tools" not in IE list: Take a screenshot to see current state. The button may be labelled differently after Excalidraw UI updates. Look for a button that reveals Frame, Mermaid, and Laser pointer options.

browser_type not replacing content: Some versions of Excalidraw use a CodeMirror editor in the Mermaid dialog. If clear=true doesn't work, click the textbox first, then mcp__byob__browser_press_key(key="Meta+a") followed by mcp__byob__browser_type with the new content.

Canvas blank after insert: Mermaid rendering takes a moment. Screenshot and wait 2–3s. If still blank, validate the mermaid syntax first: mmdc --input <file.mmd> --output /tmp/test.svg.

localStorage returns null: The canvas hasn't been saved yet. Insert a diagram first. If elements were inserted but localStorage is still empty, click on the canvas to trigger an auto-save, then re-eval.

json.loads fails on scene_raw.txt: The eval output is double-JSON-encoded (a JSON string whose value is a JSON array). Always json.loads(json.loads(raw)) — two unwrap steps.

excalidraw-export outputs blank PNG: Open the .excalidraw file and check that elements is non-empty. An empty elements array produces a blank image.

excalidraw-export not found: Install via npm install -g @moona3k/excalidraw-export. If the global npm bin isn't on PATH, use npx @moona3k/excalidraw-export.