| name | markdown-mermaid-export |
| description | Render Mermaid code blocks from Markdown files to high-quality SVG + PNG images using the MermaidChart theme. Use when the user wants to export, render, batch-convert, or screenshot Mermaid diagrams, or mentions mermaid-to-image, mermaid PNG, or diagram export. |
Render Mermaid Diagrams
Batch-extract Mermaid code blocks from a Markdown file and render them as SVG + PNG using the MermaidChart theme — matching the Cursor/VS Code MermaidChart extension appearance.
Prerequisites
- MermaidChart VS Code extension — installed in Cursor or VS Code (marketplace link)
- Puppeteer — installed globally:
npm i -g puppeteer or pnpm add -g puppeteer
- Node.js ≥ 18
Quick Start
Determine the script path based on where this skill is installed:
| Install type | Script path |
|---|
| Personal | ~/.cursor/skills/markdown-mermaid-export/scripts/markdown-mermaid-export.sh |
| Project | .cursor/skills/markdown-mermaid-export/scripts/markdown-mermaid-export.sh |
| Cloned repo | <repo>/scripts/markdown-mermaid-export.sh |
bash <script-path> <markdown-file>
Output
Files are written to {filename}-mermaid/ next to the source Markdown:
Untitled-{N}.png — 8x high-DPI screenshot, full MermaidChart theme fidelity (gradient borders, shadows). Compatible with WPS, Office, Feishu, Google Docs, etc.Untitled-{N}.svg — sanitized standalone SVG for browsers and technical docs.
The output directory is cleaned before each run to avoid stale files.
Configuration
Environment variables (all optional):
| Variable | Default | Description |
|---|
MERMAID_SCALE | 8 | PNG device scale factor (e.g. 2, 4, 8) |
MERMAID_THEME | mc | Mermaid theme name passed to the renderer |
Example:
MERMAID_SCALE=4 bash <script-path> doc.md
How It Works
- Auto-discovery: finds the MermaidChart extension and Puppeteer dynamically — no hardcoded paths, survives version upgrades
- Rendering engine: loads the extension's bundled Mermaid library in headless Chromium for pixel-accurate output
- PNG: screenshots from the original rendered DOM (preserves all visual effects)
- SVG sanitization: converts
foreignObject to native <text>, strips CSS animations/filters, converts hsl()/rgba() to hex — maximizing cross-renderer compatibility
Trigger Examples
- "把文档里的 Mermaid 图导出成图片"
- "render mermaid diagrams from README.md"
- "export architecture diagrams to PNG"
- "批量渲染 mermaid 为 SVG"
