mermaid-diagram

Generate Mermaid diagrams embedded in markdown that communicate clearly — showing relationships, flows, and structure that words alone can't express.

See examples.md for ready-to-use templates for each diagram type. Official syntax reference: https://mermaid.js.org/

---

Core Philosophy

• Diagrams should clarify, not decorate — every element must serve a purpose
• Text-first — Mermaid is text-based, version-controllable, and diff-friendly
• Right diagram for the job — pick the type that matches the concept (see Decision Guide)
• Validate before sharing — test in Mermaid Live Editor or render locally with mmdc

---

Diagram Type Decision Guide

---

Flowcharts

The most common diagram type. Use for workflows, decision trees, and process flows.

Direction

Node Shapes

Arrow Types

Subgraphs

Group related nodes into labeled containers:

subgraph Title
  direction LR
  A --> B
end

---

Sequence Diagrams

Use for API flows, service interactions, and request/response patterns. Ideal for documenting routes, middleware chains, and client-server communication.

Syntax

---

Class Diagrams

Use for data models, ORM entities, and object relationships.

Relationships

Class Definition

class ClassName {
  +String publicField
  -Number privateField
  #Date protectedField
  +methodName() ReturnType
  -privateMethod() void
}

---

ER Diagrams

Use for database schema relationships and database design.

Relationship Syntax

Entity Definition

ENTITY {
  string fieldName PK "Primary Key"
  string otherField FK "Foreign Key"
  number numericField
  date dateField
}

---

State Diagrams

Use for component lifecycle, auth flows, or any finite state machine.

Syntax

---

Gantt Charts

Use for project planning, sprint timelines, implementation plans.

Syntax

gantt
  dateFormat YYYY-MM-DD
  title Project Timeline
  section Phase 1
    Task A :a1, 2024-01-01, 5d
    Task B :after a1, 3d
  section Phase 2
    Task C :2024-01-10, 7d

Duration formats: 1d (days), 1w (weeks), 1h (hours) Dependencies: after taskId for sequential tasks

---

Styling and Theming

Inline Styles

style nodeId fill:#f9f,stroke:#333,stroke-width:2px
classDef className fill:#bbf,stroke:#333
class nodeId className

Theme Configuration

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#ff6b6b'}}}%%

Available themes: default, dark, forest, neutral, base (customizable)

---

Best Practices

Do

• Pick the right direction — LR for timelines/flows, TD for hierarchies/decisions
• Label edges — unlabeled arrows force the reader to guess the relationship
• Use subgraphs — group related nodes to reduce visual complexity
• Keep nodes concise — short labels, no paragraphs in boxes
• Use consistent naming — camelCase for IDs, readable text for labels
• Validate syntax — test in Mermaid Live Editor before committing
• Wrap in markdown — use triple-backtick mermaid code blocks
• Quote labels with special characters — A["POST /orders (retry)"]: parentheses, slashes, :, #, | and < / > inside an unquoted label break the parser on many renderers
• Keep node IDs plain — letters and digits only (orderSvc, not order-svc.v2); put the readable text in the label
• Avoid end as a bare node ID or label word in flowcharts — it closes a subgraph; write End or quote it

Don't

• Don't exceed ~20 nodes per diagram — split into multiple diagrams instead
• Don't use flowcharts for everything — sequence diagrams are better for API flows
• Don't mix directions — stick to one direction per flowchart (LR or TD)
• Don't hardcode colors unless necessary — let the theme handle consistency
• Don't use invisible links (~~~) as a first resort — fix the layout with direction/grouping first

---

Rendering

In Markdown

GitHub, GitLab, Notion, and most markdown renderers support mermaid blocks natively:

```mermaid
flowchart LR
  A --> B
```

CLI Rendering

If mmdc (Mermaid CLI) is available:

# PNG output
mmdc -i diagram.md -o diagram.png

# SVG output
mmdc -i diagram.md -o diagram.svg -t dark

# With custom width
mmdc -i diagram.md -o diagram.png -w 1200

Validation

Before sharing any diagram:

1. Check syntax in Mermaid Live Editor
2. Verify all arrows connect to valid node IDs
3. Ensure labels are readable at the rendered size
4. Test with the intended theme (light/dark)