Skip to content
agent-ready-repo

Render Mermaid diagrams to images

Convert Mermaid fences into PNG or SVG assets and optionally rewrite the Markdown to reference them.

Use this when: Your Markdown has Mermaid fenced blocks and the target tool (Confluence, PDF pipeline, or slide deck) doesn’t render Mermaid live. Prerequisites: Mermaid CLI (mmdc) installed globally via npm (npm install -g @mermaid-js/mermaid-cli); no Python dependencies beyond stdlib. Result: Rendered PNG (or SVG) image files and a rewritten Markdown copy with every Mermaid fence replaced by an image reference.

Your Markdown has ```mermaid fenced blocks, and the tool you’re shipping to doesn’t render Mermaid live — Confluence, a PDF pipeline, a slide deck. The mermaid-renderer skill extracts each fence, renders it to a PNG (or SVG), and writes a rewritten copy of your Markdown with every fence swapped for an image reference. Your original file stays untouched.

Before you start

Section titled “Before you start”

The renderer shells out to the Mermaid CLI (mmdc). Install it once:

Terminal window
npm install -g @mermaid-js/mermaid-cli

If your project already ships mmdc in a local node_modules/, that works too — the script finds mmdc on your PATH. There are no Python dependencies beyond the standard library.

Check it’s wired up:

Terminal window
python scripts/render_mermaid.py --check

Exit 0 means mmdc is ready. Exit 2 means it isn’t installed — run the npm install above. The skill won’t install it for you.

Render the diagrams

Section titled “Render the diagrams”
Terminal window
python scripts/render_mermaid.py --input report.md --output-dir ./rendered

That writes, into ./rendered/:

  • mermaid-1.png, mermaid-2.png, … — one image per block, numbered in document order.
  • report.md — a rewritten copy where each fence is replaced by a standard Markdown image reference (![](https://github.com/eugenelim/agent-ready-repo/blob/main/guides/converters/how-to/mermaid-1.png)).

The stdout summary gives you OUTPUT_DIR, REWRITTEN (the rewritten file’s path), and DIAGRAMS (the count). The images and the rewritten Markdown together are a self-contained bundle.

Common variations

Section titled “Common variations”
  • SVG instead of PNG: add --format svg.
  • A different look: --theme forest|dark|neutral (default is default), --background transparent or --background "#f0f0f0" (default white).
  • Fixed dimensions: --width and --height pass straight through to mmdc.
  • Rename the outputs: --prefix diagram gives you diagram-1.png.

The full flag list is in the reference.

Pitfalls

Section titled “Pitfalls”
  • No Mermaid blocks. The script reports DIAGRAMS: 0, copies your input through unchanged, and exits 0. Nothing breaks.
  • A block fails to render. The script keeps going on the rest, writes a mermaid-N.error.txt where the image would have been, leaves that fence intact in the rewritten Markdown, and exits non-zero with a failure count. Check the error file for the syntax problem.
  • Unknown theme. mmdc rejects it and lists the valid choices. Pick one from the list.
  • Untrusted input. The renderer runs mmdc on whatever fences it finds. Don’t point it at Markdown from an untrusted source without a separate sanitization step.

Next steps

Section titled “Next steps”