Creating Mermaid Diagrams

Mermaid Diagrams

Generate .mmd text files and export to PNG/SVG/PDF using mmdc (local) or Kroki API (no install).

Key advantage: Text-based syntax with fully automatic layout — no x/y coordinates needed.

Prerequisites

Option A: Local (mmdc)

npm install -g @mermaid-js/mermaid-cli
mmdc --version

Option B: Kroki API (no install)

curl --version  # Just need curl

Workflow

0. Update check (notify, don't pull) — first use per conversation. Throttle to once per 24 h via <this-skill-dir>/.last_update; never mutate the skill directory without explicit user consent.

• If .last_update exists and is <24 h old, skip this step entirely.
• Otherwise, fetch the latest tag from upstream:

     git -C <this-skill-dir> ls-remote --tags origin 'v*' 2>/dev/null \
       | awk '{print $2}' | sed 's|refs/tags/||' | sort -V | tail -1

• Compare with this skill's metadata.version from the frontmatter. If the upstream tag is strictly newer (semver), tell the user one line and ask:

"A newer version of this skill is available: vX.Y.Z → vA.B.C. Want me to git pull?"

If they say yes, run git -C <this-skill-dir> pull --ff-only. Refresh .last_update either way so the prompt doesn't repeat for 24 hours.

• If upstream is the same or older, refresh .last_update silently and continue.
• On any failure (offline, not a git checkout — e.g. ClawHub-installed copy, read-only path, no permission), swallow the error silently and continue with the user's task. Do not mention the failure.

1. Check deps — try mmdc --version, fallback to Kroki if unavailable 2. Pick diagram type — choose from table below 3. Generate — write .mmd file to disk 4. Validate — run validation (REQUIRED before export) 5. Export — use mmdc or Kroki API to produce PNG/SVG/PDF 6. Report — tell user the output file paths

Validation (Required)

NEVER export a diagram without validating first.

# Validate with mmdc (local)
mmdc -i diagram.mmd -o /tmp/test.png 2>&1

# Validate with Kroki (if mmdc unavailable)
curl -s -X POST -H "Content-Type: text/plain" --data-binary @diagram.mmd https://kroki.io/mermaid/svg -o /tmp/test.svg && echo "Valid" || echo "Invalid"

# If error, fix the .mmd file and validate again
# Only proceed to export after validation passes

Common validation errors:

• Missing quotes around labels with special characters
• Wrong arrow syntax (use ->> for sequence, --> for flowchart)
• Undeclared participants in sequence diagrams

Diagram Types

Syntax Reference

Flowchart: See reference/FLOWCHART.md Sequence: See reference/SEQUENCE.md Class & ER: See reference/CLASS-ER.md Other types: See reference/OTHER-TYPES.md

Examples

Example 1: API Authentication Flow

User prompt:

Create a sequence diagram for JWT authentication

Generated `.mmd`:

sequenceDiagram
  participant C as Client
  participant G as API Gateway
  participant A as Auth Service
  participant D as Database

  C->>G: POST /login {email, password}
  G->>A: validate(credentials)
  A->>D: SELECT user WHERE email=?
  D-->>A: user record
  A-->>A: verify password hash
  A-->>G: 200 OK + JWT token
  G-->>C: {token: "eyJhbG..."}

Output files: auth-flow.mmd + auth-flow.png

---

Example 2: Microservices Architecture

User prompt:

Draw an e-commerce microservices architecture

Generated `.mmd`:

flowchart TD
  subgraph Clients
    M[Mobile App]
    W[Web App]
  end

  GW[API Gateway]

  subgraph Services
    US[User Service]
    OS[Order Service]
    PS[Product Service]
    PAY[Payment Service]
  end

  subgraph Data
    UDB[(User DB)]
    ODB[(Order DB)]
    PDB[(Product DB)]
    REDIS[(Redis Cache)]
  end

  M & W --> GW
  GW --> US & OS & PS & PAY
  US --> UDB
  OS --> ODB
  PS --> PDB
  PAY --> REDIS

Output files: ecommerce-arch.mmd + ecommerce-arch.png

---

Example 3: Order State Machine

User prompt:

Show order lifecycle states

Generated `.mmd`:

stateDiagram-v2
  [*] --> Pending : order created
  Pending --> Confirmed : payment success
  Pending --> Cancelled : timeout/cancel
  Confirmed --> Shipped : dispatched
  Shipped --> Delivered : received
  Delivered --> [*]
  Cancelled --> [*]

Output files: order-states.mmd + order-states.png

Export Commands

Option 1: Local Export (mmdc)

Requires mmdc installed locally. Best for offline use.

# PNG (recommended: 2048px wide, white background)
mmdc -i diagram.mmd -o diagram.png -w 2048 --backgroundColor white

# PNG with theme (default | dark | neutral | forest | base)
mmdc -i diagram.mmd -o diagram.png -w 2048 --backgroundColor white --theme neutral

# SVG
mmdc -i diagram.mmd -o diagram.svg

# PDF
mmdc -i diagram.mmd -o diagram.pdf

Option 2: Kroki API (No Install Required)

Use Kroki when mmdc is not available. No local dependencies needed.

# SVG via Kroki
curl -X POST -H "Content-Type: text/plain" --data-binary @diagram.mmd https://kroki.io/mermaid/svg -o diagram.svg

# PNG via Kroki
curl -X POST -H "Content-Type: text/plain" --data-binary @diagram.mmd https://kroki.io/mermaid/png -o diagram.png

# PDF via Kroki
curl -X POST -H "Content-Type: text/plain" --data-binary @diagram.mmd https://kroki.io/mermaid/pdf -o diagram.pdf

Kroki advantages:

• No local installation required
• Works on any system with curl
• Supports 20+ diagram types (PlantUML, GraphViz, D2, etc.)

When to use Kroki:

• mmdc installation fails
• Quick one-off diagrams
• CI/CD pipelines without Node.js

Common Mistakes

Class & ER Diagram Syntax

Class Diagram

Basic Structure

classDiagram
  class User {
    +String name
    +String email
    -String passwordHash
    +login() bool
    +logout()
  }

  class Order {
    +int id
    +Date createdAt
    +float total
    +place()
    +cancel()
  }

  User "1" --> "*" Order : places

Visibility Modifiers

Relationships

Cardinality

classDiagram
  User "1" --> "*" Order : places
  Order "1" --> "1..*" OrderItem : contains
  Product "0..*" --> "0..*" Category : belongs to

---

ER Diagram

Basic Structure

erDiagram
  USER ||--o{ ORDER : places
  ORDER ||--|{ ORDER_ITEM : contains
  PRODUCT ||--o{ ORDER_ITEM : "included in"

  USER {
    int id PK
    string name
    string email
    datetime created_at
  }

  ORDER {
    int id PK
    int user_id FK
    float total
    string status
  }

  ORDER_ITEM {
    int order_id FK
    int product_id FK
    int quantity
  }

Relationship Notation

Attribute Types

erDiagram
  PRODUCT {
    int id PK "Primary key"
    string name "Product name"
    float price
    int category_id FK "Foreign key"
    string sku UK "Unique key"
  }

Markers: PK (primary), FK (foreign), UK (unique)

Flowchart Syntax

Basic Structure

flowchart TD
  A[Client] --> B[API Gateway]
  B --> C[Auth Service]
  B --> D[Order Service]
  D --> E[(Order DB)]
  C --> F[(User DB)]

  subgraph Services
    C
    D
  end

Direction

Node Shapes

Arrow Types

Labels on Arrows

flowchart LR
  A -->|yes| B
  A -->|no| C
  B -->|"with quotes"| D

Subgraphs

flowchart TD
  subgraph "Frontend Layer"
    A[Web App]
    B[Mobile App]
  end

  subgraph "Backend Layer"
    C[API Server]
    D[Worker]
  end

  A & B --> C
  C --> D

Special Characters

Wrap in quotes for special characters:

flowchart LR
  A["Node: with colon"]
  B["Node (with parens)"]
  A --> B

Other Diagram Types

State Diagram

stateDiagram-v2
  [*] --> Pending
  Pending --> Processing : payment_received
  Processing --> Shipped : packed
  Shipped --> Delivered : received
  Processing --> Cancelled : cancel
  Pending --> Cancelled : cancel
  Delivered --> [*]
  Cancelled --> [*]

Composite States

stateDiagram-v2
  [*] --> Active

  state Active {
    [*] --> Idle
    Idle --> Running : start
    Running --> Idle : stop
  }

  Active --> Terminated : shutdown
  Terminated --> [*]

---

Git Graph

gitGraph
  commit id: "Initial commit"
  branch develop
  checkout develop
  commit id: "Add feature A"
  commit id: "Add feature B"
  checkout main
  merge develop id: "Release v1.0"
  branch hotfix
  checkout hotfix
  commit id: "Fix critical bug"
  checkout main
  merge hotfix id: "Hotfix v1.0.1"

---

Gantt Chart

gantt
  title Project Timeline
  dateFormat YYYY-MM-DD

  section Planning
  Requirements     :a1, 2024-01-01, 7d
  Design           :a2, after a1, 5d

  section Development
  Backend API      :b1, after a2, 14d
  Frontend UI      :b2, after a2, 14d

  section Testing
  Integration Test :c1, after b1, 7d

---

Pie Chart

pie title Language Distribution
  "JavaScript" : 45
  "Python" : 30
  "Go" : 15
  "Other" : 10

---

Mind Map

mindmap
  root((Project))
    Frontend
      React
      CSS
      TypeScript
    Backend
      Node.js
      PostgreSQL
      Redis
    DevOps
      Docker
      Kubernetes
      CI/CD

---

C4 Context Diagram

C4Context
  title System Context Diagram

  Person(user, "User", "A user of the system")
  System(system, "Main System", "The core application")
  System_Ext(external, "External API", "Third-party service")

  Rel(user, system, "Uses")
  Rel(system, external, "Calls")

Sequence Diagram Syntax

Basic Structure

sequenceDiagram
  participant C as Client
  participant G as API Gateway
  participant A as Auth Service
  participant D as Database

  C->>G: POST /login
  G->>A: validate(credentials)
  A->>D: query user
  D-->>A: user record
  A-->>G: 200 OK + token
  G-->>C: {token: "..."}

Participants

Declare in desired left-to-right order:

sequenceDiagram
  participant A as Alice
  participant B as Bob
  actor U as User

• participant — box shape
• actor — stick figure

Arrow Types

Activation Boxes

sequenceDiagram
  participant C as Client
  participant S as Server

  C->>+S: request
  S-->>-C: response

Or explicit:

sequenceDiagram
  C->>S: request
  activate S
  S-->>C: response
  deactivate S

Notes

sequenceDiagram
  participant A
  participant B

  Note left of A: Left note
  Note right of B: Right note
  Note over A,B: Spanning note

Loops and Conditionals

sequenceDiagram
  participant C as Client
  participant S as Server

  loop Every 5 seconds
    C->>S: heartbeat
  end

  alt success
    S-->>C: 200 OK
  else failure
    S-->>C: 500 Error
  end

  opt optional step
    C->>S: extra call
  end

Parallel Execution

sequenceDiagram
  par Task A
    A->>B: do A
  and Task B
    A->>C: do B
  end