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

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 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

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"