Tutorial •
|

Introduction to Mermaid: Create Diagrams with Code

Learn what Mermaid is and how to use simple markdown-like text to generate high-quality flowcharts, sequence diagrams, gantt charts, and more.

What is Mermaid?

Mermaid is a JavaScript-based diagramming and charting tool that renders Markdown-inspired text definitions to create and modify diagrams dynamically.

Why Choose Mermaid?

  • Version Control Friendly: Diagrams are stored as pure text, making them easy to track, compare, and merge with Git.
  • Efficiency: No more struggling with drag-and-drop UI. Type your logic, and let Mermaid handle the layout.
  • Maintainability: Updating a complex diagram is as simple as changing a few lines of text.
  • Wide Integration: Native support in GitHub, GitLab, Notion, Obsidian, and many other developer tools.

Beyond Flowcharts: What Can You Create?

Mermaid is incredibly versatile. Here are some of the most popular diagram types:

1. Sequence Diagrams

Perfect for illustrating how processes operate with one another and in what order.

Code Example:

sequenceDiagram
    Alice->>John: Hello John, how are you?
    John-->>Alice: Great!
    Alice-)John: See you later!

Rendered Result:

sequenceDiagram
    Alice->>John: Hello John, how are you?
    John-->>Alice: Great!
    Alice-)John: See you later!

2. Gantt Charts

Useful for project management and tracking schedules.

Code Example:

gantt
    title A Gantt Diagram
    dateFormat  YYYY-MM-DD
    section Section
    A task           :a1, 2026-01-01, 30d
    Another task     :after a1  , 20d

Rendered Result:

gantt
    title A Gantt Diagram
    dateFormat  YYYY-MM-DD
    section Section
    A task           :a1, 2026-01-01, 30d
    Another task     :after a1  , 20d

3. State Diagrams

Ideal for representing the states of a system and the transitions between them.

Code Example:

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

Rendered Result:

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

4. Entity Relationship Diagrams (ERD)

Great for database design and visualizing data structures.

Code Example:

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE-ITEM : contains
    CUSTOMER }|..|{ DELIVERY-ADDRESS : uses

Rendered Result:

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE-ITEM : contains
    CUSTOMER }|..|{ DELIVERY-ADDRESS : uses

Styling and Customization

Mermaid allows you to customize the look of your diagrams using themes (default, forest, dark, neutral) and CSS-like styling for individual nodes. You can even define classes to reuse styles across multiple elements.

Try It Now

Ready to dive in? You can write, preview, and export your diagrams in real-time using our Mermaid Online Editor. It features:

  • Instant Rendering: See changes as you type.
  • Multiple Themes: Switch between light and dark modes easily.
  • Export Options: Save your work as high-quality PNG or SVG files.

Mastering Mermaid will significantly improve your documentation and technical communication efficiency. Start coding your diagrams today!

Related Articles