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.svg
    ├── diagram-2.svg
    └── architecture-diagram.svg

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

SVG too large/small

The tool auto-sizes based on diagram content. For custom sizing, edit the generated SVG or use CSS in your document.

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