Ffrank.blog
web2025년 1월 22일8 min read

The Complete Guide to Mermaid Diagrams - Drawing Diagrams with Markdown

Learn how to easily draw flowcharts, sequence diagrams, class diagrams, and more in Markdown documents using Mermaid.js.

FFrank Advenoh
#mermaid#diagram#markdown
Contents · 28

1. What is Mermaid?

Mermaid is a JavaScript library that generates diagrams using a Markdown-like text-based syntax. Since you can write diagrams like code, they are easy to version-control and can be managed alongside your documentation.

1.1 Key Features

  • Write diagrams as text
  • Version-control with Git
  • Supports various diagram types
  • Natively supported in GitHub, GitLab, Notion, and more

2. Flowchart

Flowcharts are used to visualize the flow of a process or algorithm.

2.1 Basic Syntax

Code:

flowchart TD
    A[Start] --> B{Check condition}
    B -->|Yes| C[Perform task]
    B -->|No| D[Other task]
    C --> E[End]
    D --> E

Rendered result:

flowchart TD
    A[Start] --> B{Check condition}
    B -->|Yes| C[Perform task]
    B -->|No| D[Other task]
    C --> E[End]
    D --> E

2.2 Setting Direction

  • TD or TB: Top to Bottom
  • BT: Bottom to Top
  • LR: Left to Right
  • RL: Right to Left

2.3 Node Shapes

Code:

flowchart LR
    A[Rectangle] --> B(Rounded rectangle)
    B --> C([Stadium])
    C --> D[[Subroutine]]
    D --> E[(Database)]
    E --> F((Circle))
    F --> G{Diamond}
    G --> H{{Hexagon}}

Rendered result:

flowchart LR
    A[Rectangle] --> B(Rounded rectangle)
    B --> C([Stadium])
    C --> D[[Subroutine]]
    D --> E[(Database)]
    E --> F((Circle))
    F --> G{Diamond}
    G --> H{{Hexagon}}

3. Sequence Diagram

A sequence diagram represents the interactions between objects in chronological order.

3.1 API Call Example

Code:

sequenceDiagram
    participant Client
    participant API Gateway
    participant Auth Service
    participant Database

    Client->>API Gateway: POST /login
    API Gateway->>Auth Service: Authentication request
    Auth Service->>Database: Query user
    Database-->>Auth Service: User information
    Auth Service-->>API Gateway: JWT token
    API Gateway-->>Client: 200 OK + Token

Rendered result:

sequenceDiagram
    participant Client
    participant API Gateway
    participant Auth Service
    participant Database

    Client->>API Gateway: POST /login
    API Gateway->>Auth Service: Authentication request
    Auth Service->>Database: Query user
    Database-->>Auth Service: User information
    Auth Service-->>API Gateway: JWT token
    API Gateway-->>Client: 200 OK + Token

3.2 Message Types

Code:

sequenceDiagram
    A->>B: Synchronous message (solid arrow)
    B-->>A: Response (dashed arrow)
    A-)B: Asynchronous message
    B--)A: Asynchronous response
    A-xB: Failure/rejection

Rendered result:

sequenceDiagram
    A->>B: Synchronous message (solid arrow)
    B-->>A: Response (dashed arrow)
    A-)B: Asynchronous message
    B--)A: Asynchronous response
    A-xB: Failure/rejection

3.3 Activation and Notes

Code:

sequenceDiagram
    participant User
    participant Server

    User->>+Server: Request
    Note right of Server: Processing...
    Server-->>-User: Response

    Note over User,Server: Communication complete

Rendered result:

sequenceDiagram
    participant User
    participant Server

    User->>+Server: Request
    Note right of Server: Processing...
    Server-->>-User: Response

    Note over User,Server: Communication complete

4. Class Diagram

A class diagram represents the relationships between classes in object-oriented design.

4.1 Basic Class Structure

Code:

classDiagram
    class Animal {
        +String name
        +int age
        +makeSound() void
        +move() void
    }

    class Dog {
        +String breed
        +bark() void
        +fetch() void
    }

    class Cat {
        +String color
        +meow() void
        +scratch() void
    }

    Animal <|-- Dog : Inheritance
    Animal <|-- Cat : Inheritance

Rendered result:

classDiagram
    class Animal {
        +String name
        +int age
        +makeSound() void
        +move() void
    }

    class Dog {
        +String breed
        +bark() void
        +fetch() void
    }

    class Cat {
        +String color
        +meow() void
        +scratch() void
    }

    Animal <|-- Dog : Inheritance
    Animal <|-- Cat : Inheritance

4.2 Relationship Notation

Code:

classDiagram
    classA --|> classB : Inheritance
    classC --* classD : Composition
    classE --o classF : Aggregation
    classG --> classH : Association
    classI ..> classJ : Dependency
    classK ..|> classL : Realization

Rendered result:

classDiagram
    classA --|> classB : Inheritance
    classC --* classD : Composition
    classE --o classF : Aggregation
    classG --> classH : Association
    classI ..> classJ : Dependency
    classK ..|> classL : Realization

5. State Diagram

A state diagram represents the state transitions of an object.

5.1 Order State Example

Code:

stateDiagram-v2
    [*] --> OrderReceived
    OrderReceived --> AwaitingPayment : Order confirmed
    AwaitingPayment --> PaymentCompleted : Payment success
    AwaitingPayment --> OrderCancelled : Payment failure
    PaymentCompleted --> PreparingShipment
    PreparingShipment --> Shipping : Dispatched
    Shipping --> Delivered : Arrived
    Delivered --> [*]
    OrderCancelled --> [*]

Rendered result:

stateDiagram-v2
    [*] --> OrderReceived
    OrderReceived --> AwaitingPayment : Order confirmed
    AwaitingPayment --> PaymentCompleted : Payment success
    AwaitingPayment --> OrderCancelled : Payment failure
    PaymentCompleted --> PreparingShipment
    PreparingShipment --> Shipping : Dispatched
    Shipping --> Delivered : Arrived
    Delivered --> [*]
    OrderCancelled --> [*]

5.2 Composite States

Code:

stateDiagram-v2
    [*] --> Active

    state Active {
        [*] --> Idle
        Idle --> Processing : start
        Processing --> Idle : done
    }

    Active --> Inactive : suspend
    Inactive --> Active : resume
    Inactive --> [*] : terminate

Rendered result:

stateDiagram-v2
    [*] --> Active

    state Active {
        [*] --> Idle
        Idle --> Processing : start
        Processing --> Idle : done
    }

    Active --> Inactive : suspend
    Inactive --> Active : resume
    Inactive --> [*] : terminate

6. Entity Relationship Diagram (ERD)

An ERD represents the relationships between entities in database design.

Code:

erDiagram
    USER ||--o{ ORDER : places
    USER {
        int id PK
        string name
        string email UK
        datetime created_at
    }

    ORDER ||--|{ ORDER_ITEM : contains
    ORDER {
        int id PK
        int user_id FK
        datetime order_date
        string status
    }

    ORDER_ITEM }|--|| PRODUCT : references
    ORDER_ITEM {
        int id PK
        int order_id FK
        int product_id FK
        int quantity
    }

    PRODUCT {
        int id PK
        string name
        decimal price
        int stock
    }

Rendered result:

erDiagram
    USER ||--o{ ORDER : places
    USER {
        int id PK
        string name
        string email UK
        datetime created_at
    }

    ORDER ||--|{ ORDER_ITEM : contains
    ORDER {
        int id PK
        int user_id FK
        datetime order_date
        string status
    }

    ORDER_ITEM }|--|| PRODUCT : references
    ORDER_ITEM {
        int id PK
        int order_id FK
        int product_id FK
        int quantity
    }

    PRODUCT {
        int id PK
        string name
        decimal price
        int stock
    }

7. Git Graph

Visualizes Git branches and commit history.

Code:

gitGraph
    commit id: "Initial commit"
    branch develop
    checkout develop
    commit id: "Develop feature A"
    branch feature/login
    checkout feature/login
    commit id: "Login UI"
    commit id: "Login logic"
    checkout develop
    merge feature/login
    checkout main
    merge develop tag: "v1.0.0"
    checkout develop
    commit id: "Develop feature B"

Rendered result:

gitGraph
    commit id: "Initial commit"
    branch develop
    checkout develop
    commit id: "Develop feature A"
    branch feature/login
    checkout feature/login
    commit id: "Login UI"
    commit id: "Login logic"
    checkout develop
    merge feature/login
    checkout main
    merge develop tag: "v1.0.0"
    checkout develop
    commit id: "Develop feature B"

8. Gantt Chart

A Gantt chart that visualizes a project schedule.

Code:

gantt
    title Project Schedule
    dateFormat YYYY-MM-DD

    section Planning
    Requirements analysis     :a1, 2026-01-01, 7d
    Design document writing    :a2, after a1, 5d

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

    section Testing
    Integration testing      :c1, after b1, 7d
    Bug fixes        :c2, after c1, 5d

    section Deployment
    Production deployment        :d1, after c2, 2d

Rendered result:

gantt
    title Project Schedule
    dateFormat YYYY-MM-DD

    section Planning
    Requirements analysis     :a1, 2026-01-01, 7d
    Design document writing    :a2, after a1, 5d

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

    section Testing
    Integration testing      :c1, after b1, 7d
    Bug fixes        :c2, after c1, 5d

    section Deployment
    Production deployment        :d1, after c2, 2d

9. Pie Chart

Code:

pie showData
    title Tech Stack Usage Ratio
    "JavaScript" : 35
    "TypeScript" : 30
    "Python" : 20
    "Go" : 10
    "Others" : 5

Rendered result:

pie showData
    title Tech Stack Usage Ratio
    "JavaScript" : 35
    "TypeScript" : 30
    "Python" : 20
    "Go" : 10
    "Others" : 5

10. Mermaid Rendering Tools

There are various tools and platforms that can render Mermaid diagrams.

10.1 Online Editors

ToolDescription
Mermaid Live EditorThe official online editor. Supports real-time preview and image export
Mermaid ChartA Mermaid editor for team collaboration

10.2 Natively Supported Platforms

The following platforms automatically render Mermaid code blocks without any additional setup.

  • GitHub - README, Issues, PRs, Wiki, etc.
  • GitLab - Markdown files, Issues, MRs, etc.
  • Notion - Select Mermaid in code blocks
  • Obsidian - Native support
  • Typora - Native support

10.3 IDE Extensions

IDEExtension
VS CodeMarkdown Preview Mermaid Support
IntelliJ / WebStormMermaid Plugin

10.4 Web Framework Integration

FrameworkLibrary
React / Next.jsmermaid (client-side rendering)
VuePressvuepress-plugin-mermaidjs
Docusaurus@docusaurus/theme-mermaid
HugoBuilt-in support (shortcode)
Jekylljekyll-mermaid

10.5 CLI Tool

# Install mermaid-cli
npm install -g @mermaid-js/mermaid-cli

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

# Export to PNG
mmdc -i diagram.mmd -o diagram.png

11. Conclusion

Mermaid lets you create diagrams from plain text, which means they live in version control next to your docs. That makes it a good fit for technical documentation, READMEs, and blog posts, where keeping a diagram in sync with the code is otherwise a chore.

11.1 References

관련 글

go

Golang Concurrency Part 11 - The Complete Guide to Visualization with go tool trace

web

Getting Started with React Native Using Expo: Building a Todo App

web

What Is Postman Flows?