Mermaid Diagram Renderer

Render mermaid diagrams to PNG and display them inline. Supports iTerm2 (imgcat) and Ghostty (kitten icat). Built for fast visual iteration.

Workflow
Prerequisites
Rendering
Iteration Rules
Mermaid Syntax Cheatsheet

Workflow

Every time you generate or modify mermaid code, immediately render and display it. Never ask "want me to render?" — just do it.

Write the mermaid code:

cat > /tmp/mermaid-diagram.mmd << 'MERMAID'
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action]
    B -->|No| D[End]
MERMAID

Render:

"${CLAUDE_SKILL_DIR}/scripts/render.sh" /tmp/mermaid-diagram.mmd

The script outputs Rendered: <path> and View: <command>. Always print the View: command for the user so they can copy-paste it to see the diagram inline. Claude Code's Bash tool captures stdout, so inline images won't display automatically.

If the user provides a specific file path, use that instead of /tmp/mermaid-diagram.mmd.

Prerequisites

On first use, check that mmdc is available:

which mmdc || echo "MISSING: Run 'npm install -g @mermaid-js/mermaid-cli'"

The display command (imgcat or kitten icat) is detected automatically based on $TERM_PROGRAM. No manual setup needed — the script falls back to open if neither is available.

Rendering

The render.sh script handles rendering with sensible defaults. It supports these flags:

--theme <name> — mermaid theme: default, dark, forest, neutral (default: default)
--width <px> — output width in pixels (default: 1200)
--bg <color> — background color (default: transparent)
--css <path> — custom CSS file for styling
--output <path> — custom output path (default: replaces .mmd with .png)

Examples:

"${CLAUDE_SKILL_DIR}/scripts/render.sh" /tmp/mermaid-diagram.mmd --theme dark

"${CLAUDE_SKILL_DIR}/scripts/render.sh" /tmp/mermaid-diagram.mmd --width 2400

"${CLAUDE_SKILL_DIR}/scripts/render.sh" /tmp/mermaid-diagram.mmd --output ~/Desktop/diagram.png

Iteration Rules

After each user edit request, update the .mmd file and re-render immediately
Show the View: command after every change — the user should never have to ask
Keep the .mmd file path consistent within a session so edits accumulate
If mmdc reports a syntax error, show the error message and fix the mermaid code before retrying
Use the cheatsheet below for syntax reference when iterating

Mermaid Syntax Cheatsheet

Graph Directions

graph TD (top-down), graph LR (left-right), graph BT (bottom-top), graph RL (right-left)

Node Shapes

A[Rectangle]    B(Rounded)    C{Diamond}
D((Circle))     E[[Subroutine]]   F[(Database)]
G>Asymmetric]   H{{Hexagon}}  I[/Parallelogram/]

Link Styles

A --> B           Solid arrow
A --- B           Solid line (no arrow)
A -.-> B          Dotted arrow
A ==> B           Thick arrow
A -->|label| B    Arrow with label
A -- text --> B   Arrow with text (alternate)

Subgraphs

subgraph Title
    A --> B
end

Styling

style A fill:#f9f,stroke:#333,stroke-width:2px
classDef highlight fill:#ff0,stroke:#333
class A,B highlight

Themes

Set via --theme flag: default, dark, forest, neutral

Or in the diagram: %%{init: {'theme': 'dark'}}%%

Sequence Diagram

sequenceDiagram
    participant A as Alice
    participant B as Bob
    A->>B: Hello
    B-->>A: Hi back
    A->>+B: Request
    B-->>-A: Response
    Note over A,B: Handshake complete

State Diagram

stateDiagram-v2
    [*] --> Idle
    Idle --> Processing: start
    Processing --> Done: finish
    Done --> [*]

Entity Relationship

erDiagram
    USER ||--o{ ORDER : places
    ORDER ||--|{ LINE_ITEM : contains

Class Diagram

classDiagram
    class Animal {
        +String name
        +makeSound()
    }
    Animal <|-- Dog
    Animal <|-- Cat

mermaid-render