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]

More content...

### Step 2: Export Diagrams to PNG

After creating/editing a document with Mermaid blocks, run:

```bash
node ~/.claude/tools/mermaid-renderer/process-document.js <document-path> --verbose

Options:

• --format=<fmt> - Output format: png (default) or svg
• --theme=<theme> - Mermaid theme: default, forest, dark, neutral
• --verbose - Show detailed progress
• --dry-run - Preview without making changes

NOTE: PNG is the default format for maximum compatibility with markdown previewers (VS Code, GitHub, Zed). Use --format=svg only when scalable vector output is specifically needed.

Step 3: Result Structure

The tool will:

1. Extract all \``mermaid` code blocks
2. Render each to SVG in diagrams/{document-name}/
3. Replace the code block with an image reference
4. 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

Integration with Mermaid Skill

This skill works together with the main Mermaid diagram skill:

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

MANDATORY workflow:

1. Create/edit mermaid code blocks in document
2. Run the export tool immediately (before any commit)
3. 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:

1. Title in diagram config (if present)
2. First node name in the diagram
3. 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:

1. Expand the <details> block to view the mermaid source
2. Edit the mermaid code directly inside the <details> block
3. Re-run the export tool
4. 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

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