mermaid-graph-renderer

name	mermaid-graph-renderer
license	Apache-2.0
description	Renders Mermaid diagrams to SVG, PNG, and PDF in both web and offline contexts. Covers client-side lazy loading, SSR trade-offs, CLI batch export, and native Rust rendering. Use when exporting diagrams to images, optimizing Mermaid rendering performance on web pages, setting up CI/CD diagram pipelines, or choosing a rendering library. Activate on "render mermaid", "export diagram", "mermaid to png", "mermaid to svg", "mermaid performance", "diagram export". NOT for writing Mermaid syntax (use mermaid-graph-writer), general image processing, or non-Mermaid diagram formats.
allowed-tools	Read,Write,Edit,Bash
argument-hint	[input-file-or-diagram] [output-format: svg|png|pdf]
metadata	{"category":"Content & Writing","tags":["mermaid","graph","renderer","render-mermaid","export-diagram"],"pairs-with":[{"skill":"mermaid-graph-writer","reason":"The writer creates diagram syntax; the renderer converts it to visual SVG/PNG output"},{"skill":"diagramming-expert","reason":"Rendering decisions (sizing, themes, fonts) complement diagram content authoring"},{"skill":"document-generation-pdf","reason":"Rendered Mermaid diagrams are embedded in generated PDF documentation"}]}
category	Data & Analytics
tags	["mermaid","diagramming","graph-rendering","visualization","documentation"]

Mermaid Graph Renderer

Renders Mermaid diagrams to production-quality SVG, PNG, and PDF in web and offline contexts. Covers the full spectrum from lazy-loaded client-side rendering to 1000x-faster native Rust batch export.

Core Constraint

Mermaid.js requires browser APIs (document.createElement, SVGTextElement.getBBox()) to compute text dimensions. Every non-browser rendering path must either embed a headless browser or reimplement the renderer from scratch. This constraint shapes every decision below.

---

When to Use

✅ Use for:

• Rendering Mermaid diagrams on web pages (performance-optimized)
• Exporting diagrams to SVG, PNG, or PDF (offline/CLI)
• Setting up CI/CD pipelines that generate diagram images
• Choosing between rendering libraries for a project
• Optimizing Mermaid load time on documentation sites

❌ NOT for:

• Writing Mermaid syntax (use mermaid-graph-writer)
• Rendering non-Mermaid formats (PlantUML, GraphViz — see Kroki)
• General image processing or manipulation

---

Rendering Decision Tree

flowchart TD
  A{Where are you rendering?} -->|Browser| B{Performance matters?}
  A -->|CLI / CI| C{Volume?}
  A -->|Server-side| D{Must avoid client JS?}

  B -->|Yes| E[Lazy-load mermaid.js]
  B -->|No| F[CDN script tag]

  C -->|1-10 diagrams| G[mermaid-cli]
  C -->|10-100 diagrams| H{Need multiple formats?}
  C -->|100+ diagrams| I[mmdr Rust renderer]

  H -->|Mermaid only| G
  H -->|Multiple languages| J[Kroki]

  D -->|Yes, zero JS| K[Build-time with Puppeteer]
  D -->|Some JS OK| E
  K -->|Slow builds warning| L[rehype-mermaid + Playwright]

---

Web Rendering

Option 1: Lazy-Loaded mermaid.js (Recommended)

Best for documentation sites, blogs, and apps where only some pages have diagrams.

How it works: Check for .mermaid elements before loading the library. The ~480 KB cost is only paid on pages that actually need it.

// Lazy load pattern — only loads mermaid.js when diagrams exist
function initMermaid() {
  const diagrams = document.querySelectorAll('.mermaid');
   (diagrams. === ) ;

   script = .();
  script. = ;
  script. =  {
    mermaid.({ : , :  });
    mermaid.({ : diagrams });
  };
  ..(script);
}


.(, initMermaid);