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

1. 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:

``bash 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.
• Check deps — try mmdc --version, fallback to Kroki if unavailable
• Pick diagram type — choose from table below
• Generate — write .mmd file to disk
• Validate — run validation (REQUIRED before export)
• Export — use mmdc or Kroki API to produce PNG/SVG/PDF
• 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

| Type | Keyword | Use for | |------|---------|---------| | Flowchart | flowchart TD/LR | processes, pipelines, decisions | | Sequence | sequenceDiagram | API calls, message passing | | Class | classDiagram | OOP models, data structures | | ER | erDiagram | database schemas | | State | stateDiagram-v2 | state machines, lifecycle | | Gantt | gantt | project timelines | | Pie | pie | proportions | | Git Graph | gitGraph | branch strategies | | C4 Context | C4Context | high-level architecture | | Mind Map | mindmap | topic breakdowns |

Syntax Reference

Flowchart: See [reference/FLOWCHART.md](reference/FLOWCHART.md) Sequence: See [reference/SEQUENCE.md](reference/SEQUENCE.md) Class & ER: See [reference/CLASS-ER.md](reference/CLASS-ER.md) Other types: See [reference/OTHER-TYPES.md](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

| Mistake | Fix | |---------|-----| | mmdc not found | npm install -g @mermaid-js/mermaid-cli | | Wrong arrow in sequence | Use ->> for request, -->> for response | | Special chars in label | Wrap in quotes: A["Label: value"] | | Blank/small output | Add -w 2048 flag | | Participant order wrong | Declare participant explicitly at top | | Subgraph name with spaces | Wrap in quotes: subgraph "My Layer" |