mermaid-render

Original：🇺🇸 English

Translated

1 scripts

Render and display Mermaid diagrams inline in iTerm2 or Ghostty. Use when creating, editing, or iterating on mermaid diagrams. Triggers on mermaid diagram work — flowcharts, sequence, state, class, ER, and XY charts.

2installs

Sourceolshansk/agent-skills

Added on2026-03-09

NPX Install

npx skill4agent add olshansk/agent-skills mermaid-render

SKILL.md Content

View Translation Comparison →

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:

bash

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

Render:

bash

"${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:

bash

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:

bash

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

bash

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

bash

"${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

text

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

Link Styles

text

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

text

subgraph Title
    A --> B
end

Styling

text

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

text

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

text

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

Entity Relationship

text

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

Class Diagram

text

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

mermaid-render

NPX Install

Tags

SKILL.md Content

Mermaid Diagram Renderer

Workflow

Prerequisites

Rendering

Iteration Rules

Mermaid Syntax Cheatsheet

Graph Directions

Node Shapes

Link Styles

Subgraphs

Styling

Themes

Sequence Diagram

State Diagram

Entity Relationship

Class Diagram