olshansk/cmd-mermaid-render

Mermaid Diagram Renderer <!-- omit in toc -->

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

<!-- TODO: Once Claude Code supports inline image passthrough, update the workflow to display directly instead of printing the view command. Tracking: https://github.com/anthropics/claude-code/issues/29254 -->

• 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