markdown-mermaid-export

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"