Diagram Types Reference

Overview

The UML Diagrams macro supports 12 Mermaid diagram types. This reference covers the syntax header, best use cases, and a minimal working example for each type - so you can choose the right diagram for your documentation and start writing immediately.

---

1. Flowchart

Header: flowchart TD (top-down) or flowchart LR (left-right)

Best for: Process flows, decision trees, approval workflows, CI/CD pipelines

Example:

flowchart TD
  A[Start] --> B{Is approved?}
  B -- Yes --> C[Deploy to Production]
  B -- No --> D[Return for Review]
  C --> E[End]
  D --> B

Direction options: TD (top-down), LR (left-right), BT (bottom-top), RL (right-left)

---

2. Sequence Diagram

Header: sequenceDiagram

Best for: API interactions, system integrations, authentication flows, service-to-service communication

Example:

sequenceDiagram
  participant User
  participant API
  participant DB
  User->>API: POST /login
  API->>DB: SELECT user WHERE email=?
  DB-->>API: User record
  API-->>User: 200 OK + JWT token

---

3. Entity Relationship Diagram (ERD)

Header: erDiagram

Best for: Database schemas, data models, domain modeling, API data structures

Example:

erDiagram
  USER {
    int id PK
    string email
    string name
  }
  ORDER {
    int id PK
    int user_id FK
    date created_at
  }
  USER ||--o{ ORDER : places

---

4. Gantt Chart

Header: gantt

Best for: Project timelines, sprint planning, release schedules, roadmaps

Example:

gantt
  title Q1 Release Plan
  dateFormat YYYY-MM-DD
  section Design
  Wireframes    :done, 2024-01-01, 2024-01-14
  section Development
  Backend API   :active, 2024-01-15, 2024-02-15
  Frontend      :2024-01-22, 2024-02-20
  section QA
  Testing       :2024-02-15, 2024-03-01
  section Launch
  Release       :milestone, 2024-03-01, 1d

---

5. Class Diagram

Header: classDiagram

Best for: Object-oriented design, software architecture, API contracts, inheritance hierarchies

Example:

classDiagram
  class Animal {
    +String name
    +int age
    +makeSound()
  }
  class Dog {
    +String breed
    +fetch()
  }
  Animal <|-- Dog

---

6. State Diagram

Header: stateDiagram-v2

Best for: Finite state machines, order lifecycle, ticket status flows, feature flag states

Example:

stateDiagram-v2
  [*] --> Open
  Open --> InProgress : Assign
  InProgress --> Review : Submit PR
  Review --> Done : Approve
  Review --> InProgress : Request Changes
  Done --> [*]

---

7. Pie Chart

Header: pie

Best for: Distribution breakdowns, budget allocation, team composition, technology stack ratios

Example:

pie title Tech Stack Distribution
  "React" : 35
  "Node.js" : 25
  "PostgreSQL" : 20
  "Redis" : 10
  "Docker" : 10

---

8. Mindmap

Header: mindmap

Best for: Brainstorming, topic hierarchies, feature breakdowns, onboarding guides

Example:

mindmap
  root((Product)
    Frontend
      React
      TypeScript
      Tailwind
    Backend
      Node.js
      REST API
      GraphQL
    Infrastructure
      AWS
      Docker
      CI/CD

---

9. Timeline

Header: timeline

Best for: Historical milestones, product history, incident timelines, project retrospectives

Example:

timeline
  title Company Milestones
  2020 : Founded
  2021 : First Product Launch
       : Series A Funding
  2022 : Reached 10,000 Users
  2023 : Expanded to 3 Countries
  2024 : IPO

---

10. Git Graph

Header: gitGraph

Best for: Branching strategies, Git workflows, release branching models, feature branch documentation

Example:

gitGraph
  commit
  branch feature/login
  checkout feature/login
  commit
  commit
  checkout main
  merge feature/login
  commit
  branch release/v1.0
  checkout release/v1.0
  commit

---

11. Block Diagram

Header: block-beta

Best for: System architecture overviews, cloud infrastructure layouts, component maps

Example:

block-beta
  columns 3
  Frontend:1
  API["API Gateway"]:1
  Backend:1
  DB[("Database")]:1
  Cache["Redis Cache"]:1
  Queue["Message Queue"]:1

---

12. Quadrant Chart

Header: quadrantChart

Best for: Feature prioritization, risk-impact matrices, technology evaluation, 2×2 analysis

Example:

quadrantChart
  title Feature Prioritization
  x-axis Low Effort --> High Effort
  y-axis Low Impact --> High Impact
  quadrant-1 Quick Wins
  quadrant-2 Strategic Bets
  quadrant-3 Fill-ins
  quadrant-4 Avoid
  Feature A: [0.3, 0.8]
  Feature B: [0.7, 0.9]
  Feature C: [0.2, 0.2]
  Feature D: [0.8, 0.3]

---

Choosing the Right Diagram Type