Mermaid Diagram Export Skill Skill

Mermaid Diagram Export Skill

Render Mermaid diagrams in documents to PNG images using the mermaid-renderer tool.

CRITICAL RULE: Always render diagrams immediately after creating or editing Mermaid code. Never commit a document with unrendered Mermaid diagrams.

Tool Location

~/.claude/tools/mermaid-renderer/
├── render-mermaid.js      # Single diagram renderer
└── process-document.js    # Full document processor

Workflow

Step 1: Create Document with Mermaid Diagrams

When creating a document with Mermaid diagrams, use the standard mermaid skill to generate the diagram code:

# My Document

Here's the architecture:

```mermaid
flowchart LR
    A[Client] --> B[API Gateway]
    B --> C[Service]

Step 3: Result Structure

The tool will:

Extract all \``mermaid` code blocks
Render each to SVG in diagrams/{document-name}/
Replace the code block with an image reference
Preserve original code in a comment for future editing

Output structure:

document.md
diagrams/
└── document/
    ├── diagram-1.png
    ├── diagram-2.png
    └── architecture-diagram.png

Document transformation:

<!-- Before -->
` ``mermaid
flowchart LR
    A --> B
` ``

<!-- After -->
![diagram-1](diagrams/document/diagram-1.png)

<details>
<summary>Mermaid Source</summary>

` ``mermaid
flowchart LR
    A --> B
` ``

</details>

IMPORTANT: Use a collapsible <details> block (not HTML comments) to preserve the source. This keeps the document clean while making the source visible and editable.

Rendering Single Diagrams

To render a single diagram without processing a full document:

# From a .mmd file
node ~/.claude/tools/mermaid-renderer/render-mermaid.js diagram.mmd output.svg

# From stdin
echo "flowchart TD; A-->B" | node ~/.claude/tools/mermaid-renderer/render-mermaid.js --stdin output.svg

# With theme
node ~/.claude/tools/mermaid-renderer/render-mermaid.js diagram.mmd output.svg --theme=dark

Supported Document Types

| Extension | Image Syntax Used | |-----------|-------------------| | .md, .markdown | ![alt](path) with HTML comment | | .html, .htm | <img> tag with HTML comment | | .mdx | JSX <img> with JSX comment | | .rst | .. image:: directive | | .adoc | image:: macro |

Integration with Mermaid Skill

This skill works together with the main Mermaid diagram skill:

Design: Use the mermaid skill to design diagrams with proper styling
Export: Use this skill to render diagrams to PNG

MANDATORY workflow:

Create/edit mermaid code blocks in document
Run the export tool immediately (before any commit)
Commit document AND generated PNGs together

DO NOT commit a document containing unrendered mermaid blocks. The render step is not optional.

Diagram Naming

Diagrams are named based on:

Title in diagram config (if present)
First node name in the diagram
Fallback: diagram-1, diagram-2, etc.

To control naming, add a title:

---
title: Architecture Overview
---
flowchart LR
    ...

→ Generates architecture-overview.svg

Editing Rendered Diagrams

To edit a previously rendered diagram:

Expand the <details> block to view the mermaid source
Edit the mermaid code directly inside the <details> block
Re-run the export tool
The image file is updated in place (document structure unchanged)

The tool automatically detects the rendered pattern (![image](path) + <details> with mermaid source) and re-renders the images without modifying the document structure.

ELK Layout Support

This renderer fully supports ELK layout for complex diagrams:

---
config:
  layout: elk
  elk:
    mergeEdges: true
---
flowchart LR
    ...

How Re-rendering Works

The tool handles two scenarios:

1. Re-rendering Existing Diagrams

When it finds the rendered pattern:

![diagram](diagrams/doc/diagram.png)

<details>
<summary>Mermaid Source</summary>

` ``mermaid
flowchart LR
    A --> B
` ``

</details>

The tool:

Extracts the mermaid code from inside <details>
Re-renders the image file in place
Does NOT modify the document (no nesting issues)

2. Initial Rendering of New Diagrams

When it finds a standalone mermaid block (not inside <details>):

` ``mermaid
flowchart LR
    A --> B
` ``

The tool:

Renders to a new image file
Wraps the block with image reference + <details> structure

Troubleshooting

"Could not find Chrome"

Puppeteer needs Chromium. Install globally: npm install -g puppeteer

Diagram doesn't render

Check Mermaid syntax at https://mermaid.live
Ensure valid ELK config if using layout: elk

Diagram renders as 53,854-byte error PNG

This is the mermaid "Syntax error in text" placeholder. Common causes:

classDef class — class is a reserved keyword. Use cls instead
Angle brackets in comments (%% <http://...>) — the renderer escapes these automatically, but if rendering standalone, wrap in escapeForHtmlPre()
\n in labels — use <br/> instead
Run bash ~/.claude/tools/mermaid-renderer/validate-diagrams.sh <doc> to test all blocks

SVG too large/small

The tool auto-sizes based on diagram content. For custom sizing, use the <img> tag with width/height attributes (see Image Sizing section below).

HTML/PDF Export (After Rendering)

After rendering diagrams to PNG, export the full document to HTML/PDF:

node ~/.claude/tools/markdown-export/convert.js <document-path> --verbose

The HTML export:

Embeds images inline as base64 data URIs (self-contained HTML)
Caps image height at 80vh so diagrams fit on screen without scrolling
Pan/zoom viewer — clicking any image opens an interactive overlay:
- Scroll wheel: zoom centered on cursor
- Click-drag: pan
- Double-click: toggle fit/1:1
- Touch: pinch-zoom and drag
- Keyboard: +/- zoom, 0 fit, 1 actual size, Esc close
Angle bracket escaping in mermaid <pre> context (prevents HTML parsing of <url> in comments)
Generates PDF via Puppeteer with rendered diagrams

Image Sizing

CRITICAL: When resizing images in markdown, you MUST use the <img> tag with size attributes. NEVER use CSS.

Correct Way (Use This)

<img src="diagrams/document/diagram.png" alt="Diagram Name" width="90%">

Or with fixed pixel width:

<img src="diagrams/document/diagram.png" alt="Diagram Name" width="600">

Wrong Way (Never Do This)

<!-- WRONG: CSS styling -->
![diagram](path.svg){: style="width: 90%" }

<!-- WRONG: Kramdown attributes -->
![diagram](path.svg){: width="90%" }

Size Guidelines

| Diagram Type | Recommended Width | |--------------|-------------------| | Simple flowcharts | width="70%" | | Complex architectures | width="90%" | | Sequence diagrams | width="80%" | | State machines | width="60%" | | ER diagrams | width="85%" |

With Details Block

When including the mermaid source in a details block:

<img src="diagrams/document/diagram.png" alt="Architecture Overview" width="90%">

<details>
<summary>Mermaid Source</summary>

` ``mermaid
flowchart LR
    A --> B
` ``

</details>

Diagrams not being re-rendered

Ensure the document has the correct pattern: ![image](path) followed by <details> with <summary>Mermaid Source</summary> and the mermaid code block. The pattern matching is strict to avoid false positives.

Example Commands

# Process a markdown file
node ~/.claude/tools/mermaid-renderer/process-document.js ./docs/README.md --verbose

# Process with dark theme
node ~/.claude/tools/mermaid-renderer/process-document.js ./docs/arch.md --theme=dark

# Dry run to see what would happen
node ~/.claude/tools/mermaid-renderer/process-document.js ./docs/README.md --dry-run

# Render single diagram
node ~/.claude/tools/mermaid-renderer/render-mermaid.js ./diagrams/flow.mmd ./output/flow.svg

Agent Skills: Mermaid Diagram Export Skill

Install this agent skill to your local

Skill Files