Mermaid Syntax Beginner's Guide: From Basics to Practice

Mermaid is a JavaScript-based diagramming and charting tool that allows users to generate various types of diagrams and visualizations using a lightweight syntax similar to Markdown. With Mermaid, you can manage diagrams as code, making version control and collaboration effortless.

Want to try writing Mermaid diagrams right away? Feel free to use our Online Mermaid Editor, which provides real-time preview to help you get started quickly.

1. Flowchart

Flowcharts are one of Mermaid’s most popular features, used to visualize steps in a process, system, or algorithm.

1.1 Basic Directions

You can specify the direction of the chart:

• TB - Top to Bottom
• BT - Bottom to Top
• RL - Right to Left
• LR - Left to Right

Code:

graph TD
    A[Start] --> B{Is it success?}
    B -- Yes --> C[End]
    B -- No --> D[Retry]
    D --> B

Preview:

graph TD
    A[Start] --> B{Is it success?}
    B -- Yes --> C[End]
    B -- No --> D[Retry]
    D --> B

1.2 Node Shapes

• [Rectangle]
• (Round Rectangle)
• ([Stadium])
• [[Subroutine]]
• [(Cylindrical)]
• ((Circle))
• {{Hexagon}}
• [/Parallelogram/]
• [\Trapezoid\]

1.3 Links

• --> Solid link with arrow
• --- Solid link without arrow
• -.-> Dotted link with arrow
• ==> Thick link with arrow

2. Sequence Diagram

Sequence diagrams are used to show the chronological sequence of interactions between objects.

Code:

sequenceDiagram
    participant Alice
    participant Bob
    Alice->>Bob: Hello Bob, how are you?
    Bob-->>Alice: I am good thanks!
    Alice-)Bob: Async message

Preview:

sequenceDiagram
    participant Alice
    participant Bob
    Alice->>Bob: Hello Bob, how are you?
    Bob-->>Alice: I am good thanks!
    Alice-)Bob: Async message

2.1 Participants

You can define participants using participant or actor keywords and set aliases with as.

2.2 Messages

• -> Solid line without arrow
• --> Dotted line without arrow
• ->> Solid line with arrowhead
• -->> Dotted line with arrowhead
• -x Solid line with a cross at the end
• --x Dotted line with a cross at the end

3. Gantt Chart

Gantt charts are used to illustrate a project schedule.

Code:

gantt
    title Project Development Plan
    dateFormat  YYYY-MM-DD
    section Design Phase
    Requirements Analysis :a1, 2026-01-01, 3d
    UI Design             :after a1, 5d
    section Development Phase
    Frontend Development  :2026-01-10, 10d
    Backend Development   :2026-01-10, 12d

Preview:

gantt
    title Project Development Plan
    dateFormat  YYYY-MM-DD
    section Design Phase
    Requirements Analysis :a1, 2026-01-01, 3d
    UI Design             :after a1, 5d
    section Development Phase
    Frontend Development  :2026-01-10, 10d
    Backend Development   :2026-01-10, 12d

4. Class Diagram

Class diagrams describe the structure of a system by showing the system’s classes, their attributes, operations (or methods), and the relationships among objects.

Code:

classDiagram
    class Animal {
        +String name
        +eat()
        +sleep()
    }
    class Duck {
        +swim()
    }
    Animal <|-- Duck

Preview:

classDiagram
    class Animal {
        +String name
        +eat()
        +sleep()
    }
    class Duck {
        +swim()
    }
    Animal <|-- Duck

4.1 Relationships

• <|-- Inheritance
• *-- Composition
• o-- Aggregation
• --> Association
• ..> Dependency

5. State Diagram

State diagrams are used to describe the behavior of a system.

Code:

stateDiagram-v2
    [*] --> Still
    Still --> [*]
    Still --> Moving
    Moving --> Still
    Moving --> Crash
    Crash --> [*]

Preview:

stateDiagram-v2
    [*] --> Still
    Still --> [*]
    Still --> Moving
    Moving --> Still
    Moving --> Crash
    Crash --> [*]

6. Pie Chart

Used to show the proportional distribution of data.

Code:

pie title Browser Market Share
    "Chrome" : 65
    "Safari" : 20
    "Firefox" : 10
    "Edge" : 5

Preview:

pie title Browser Market Share
    "Chrome" : 65
    "Safari" : 20
    "Firefox" : 10
    "Edge" : 5

7. Git Graph

Used to simulate Git branches and commit history.

Code:

gitGraph
    commit
    commit
    branch develop
    checkout develop
    commit
    commit
    checkout main
    merge develop
    commit

Preview:

gitGraph
    commit
    commit
    branch develop
    checkout develop
    commit
    commit
    checkout main
    merge develop
    commit

Conclusion

Mermaid provides an extremely efficient way to create and maintain diagrams in technical documentation. With simple text descriptions, you can focus on the logic of your content without wasting time on layout and drawing tools.

Don’t forget, you can practice this syntax anytime in our Online Mermaid Editor and see the results in real-time!