Mermaid Export (Python)
Export .mermaid / .mmd files to PNG, SVG, or PDF — even on locked-down corporate machines where other Mermaid exporters fail.
Instead of bundling a headless Chromium (which corporate proxies and endpoint security love to break), this extension delegates rendering to a small Python script that drives a browser you already have (Microsoft Edge or Chrome) via Playwright. Fully local: no cloud services, no diagram data leaves your machine.
⚠️ Prerequisite: Python + Playwright
Windows:
pip install playwright
If pip needs your corporate proxy: pip install --proxy http://your-proxy:8080 playwright.
macOS (Homebrew Python is PEP 668 "externally managed" — use a venv):
python3 -m venv ~/.mermaid-export-venv
~/.mermaid-export-venv/bin/pip install playwright
Then set mermaidExportPy.pythonPath to ~/.mermaid-export-venv/bin/python3 (full path).
No browser? Auto-detect tries Edge, then Chrome, then Playwright's own Chromium. To get the latter: python -m playwright install chromium.
Usage
Right-click a .mermaid or .mmd file in the Explorer (or the editor tab) and choose:
- Mermaid: Export to PNG (Python) — high-DPI raster, ideal for Word/Confluence
- Mermaid: Export to SVG (Python)
- Mermaid: Export to PDF (Python)
- Mermaid: Export to PNG + SVG (Python) — both in one run
Output is saved next to the source file. Progress and errors appear in the Mermaid Export (Python) output channel.
Why PNG export works here when other extensions fail
Diagrams using HTML labels (<b>, <br/>) render via SVG foreignObject, which breaks canvas-based PNG exporters and produces SVGs that Word/Visio can't open. This extension screenshots a real browser render, so HTML-label diagrams export pixel-perfect.
Tip: if you need a portable SVG (for Visio/Illustrator/Word), avoid HTML tags in labels and add this directive as line 1 — the setting is needed at both levels:
%%{init: {"htmlLabels": false, "flowchart": {"htmlLabels": false}}}%%
Consistent fonts between preview and export
Exports render in a bare browser page, so Mermaid falls back to Trebuchet MS unless you pin a font. To match the VS Code preview (OS system font) on both macOS and Windows, put this on line 1:
%%{init: {"themeVariables": {"fontFamily": "-apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif"}}}%%
Settings
| Setting |
Default |
Description |
mermaidExportPy.pythonPath |
python |
Python executable (py, python3, or full path — on macOS use the venv path) |
mermaidExportPy.scriptPath |
(bundled) |
Override path to render_mermaid.py |
mermaidExportPy.scale |
2 |
PNG device scale factor |
mermaidExportPy.browserPath |
(auto) |
Explicit browser exe if Edge/Chrome isn't auto-detected |
Troubleshooting
- Commands missing / extension disabled — VS Code Restricted Mode disables extensions that run external processes. Trust the workspace (click the badge in the status bar).
- "Could not start Python" — set
mermaidExportPy.pythonPath (Windows often py; macOS the venv python3).
- Browser not found — set
mermaidExportPy.browserPath, e.g. C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe.
- Export looks stale — fixed in 0.0.2 (dirty files are now saved before export).
- Timeout — usually a Mermaid syntax error; check the output channel for the renderer log.
Changelog
0.0.5 — Icon: white background behind the full seal including the outer text band; grey/dark text; transparent outside the circle.
0.0.4 — Updated extension icon (white seal variant, transparent outside the circle).
0.0.3 — SVG export now serialized as valid XML (fixes "undefined entity" parse errors when diagrams contain or other HTML entities).
0.0.2 — Export PNG + SVG combined command; all formats in editor-tab menu; save dirty files before export; extension icon.
0.0.1 — Initial release.
License
MIT
