| name | mermaid-rendering |
| description | Render Mermaid diagrams visually — local HTML, browser screenshots, mermaid.ink, and mermaid.live pitfalls. Use when a diagram needs to be shown to the user as an image, not just as code blocks. |
| tags | ["mermaid","diagrams","visualization","browser","c4","flowchart","architecture"] |
Mermaid Rendering
Render Mermaid diagrams to visual output (screenshots, images) from code.
When to Use
- User asks to "show", "render", or "generate" a diagram visually (not just code)
- Wiki entities need architecture diagrams
- C4, flowchart, sequence, ER, or any Mermaid syntax needs visual verification
Method 1: Local HTML File (Recommended)
Create a standalone HTML, open in browser, screenshot with browser_vision().
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<style>
body { font-family: -apple-system, sans-serif; background: #1a1a2e; color: #eee; padding: 20px; }
h1 { color: #e94560; font-size: 1.4em; }
h2 { color: #0f3460; background: #e94560; display: inline-block; padding: 4px 12px; border-radius: 4px; font-size: 1.1em; }
.diagram { background: #fff; border-radius: 8px; padding: 20px; margin: 16px 0; overflow-x: auto; }
</style>
<script type="module">
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
mermaid.initialize({ startOnLoad: true, theme: 'default' });
</script>
</head>
<body>
<h1>Title</h1>
<div class="diagram">
<pre class="mermaid">
flowchart TD
A --> B
</pre>
</div>
</body>
</html>
Steps:
write_file(path='/tmp/mermaid-diagram.html', content=...)browser_navigate(url='file:///tmp/mermaid-diagram.html')browser_vision(question='Describe the rendered diagram')- Share screenshot path with user via MEDIA: tag (if on messaging platform)
Multiple diagrams on one page
Works fine — just add more <div class="diagram"><pre class="mermaid">...</pre></div> blocks.
C4 diagrams specifically
Add c4: { useMaxWidth: false } to mermaid config:
mermaid.initialize({ startOnLoad: true, theme: 'default', c4: { useMaxWidth: false } });
Method 2: mermaid.ink API
Quick image URL — no browser needed:
https://mermaid.ink/img/{base64-encoded-diagram}
import base64
diagram = 'flowchart TD\n A --> B'
encoded = base64.urlsafe_b64encode(diagram.encode()).decode()
url = f"https://mermaid.ink/img/{encoded}"
Limitations: size limits, no C4 theme customization, may rate-limit.
Pitfalls
mermaid.live — DO NOT use for automation
- Promotional modal blocks the editor on load ("Try the full Mermaid experience")
- Monaco editor global
monaco is NOT exposed — cannot programmatically set content
browser_type into the CodeMirror/Monaco editor is unreliable- The "Stay on mermaid.live" button dismisses the modal but content injection still fails
- Use local HTML file instead — always works, no modals, full control
Common rendering issues
- C4 diagrams too narrow: add
c4: { useMaxWidth: false } to mermaid config
- CDN blocked in proxy environments: use
https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs (most reliable CDN)
- Dark theme diagrams on dark backgrounds: use
theme: 'default' in mermaid config, keep .diagram background white
- Chinese text garbled: ensure
<meta charset="UTF-8"> is in the HTML head
Output Conventions
- Temp HTML:
/tmp/mermaid-{topic}.html
- Permanent markdown (with mermaid code blocks):
~/wiki/assets/c4-{topic}.md or project-appropriate location
- Screenshots land in
~/.hermes/cache/screenshots/ automatically from browser_vision()
