How to Create Diagrams Using Mermaid

September 22, 20243 min read

almost 2 years ago0views

Mermaid allows you to easily generate flowcharts, sequence diagrams, Gantt charts, and other visualizations directly from text using a simple syntax. It is especially useful in environments such as Markdown, documentation, and wikis.

What You Will Learn:

Setting up Mermaid
Creating a flowchart
Building a sequence diagram
Generating a Gantt chart

1. Setting Up Mermaid

Mermaid is easy to integrate into HTML and Markdown files. You can use it with various tools such as GitHub README, Markdown editors like Typora, or static site generators like Jekyll.

a. Use Mermaid with HTML:

You can load Mermaid directly into an HTML page using the <script> tag:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Mermaid Diagram Example</title>
    <script type="module">
      import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs';
      mermaid.initialize({startOnLoad:true});
    </script>
</head>
<body>
    <div class="mermaid">
      graph TD;
        A-->B;
        B-->C;
        C-->D;
    </div>
</body>
</html>

b. Using Mermaid in Markdown:

In Markdown-based platforms (like GitHub, Notion, or some documentation platforms), Mermaid syntax is used as follows:

<pre> ```mermaid graph TD; A-->B; B-->C; C-->D; ``` </pre>

Simply wrap your Mermaid code within ```mermaid code block syntax.

2. Creating a Flowchart

A flowchart shows the flow of a process, decision, or system. Mermaid’s syntax is simple, enabling you to define nodes and edges with basic relationships.

Example Flowchart Code:

graph TD;
    Start --> Process1;
    Process1 --> Decision{Is it working?};
    Decision -->|Yes| Success[Success];
    Decision -->|No| Fix[Fix the issue];
    Fix --> Process1;

Explanation:

graph TD; defines the graph direction (top to down).
Each line represents nodes (Start, Process1, etc.) and their relationships (using -->).
Curly braces {} define decision points, while square brackets [] define regular nodes.

Resulting Flowchart:

Start → Process1 → Decision
Decision → Yes → Success
Decision → No → Fix → Process1

3. Building a Sequence Diagram

A sequence diagram illustrates how objects interact in a sequence of events. It is often used in software engineering to visualize how functions or classes interact.

Example Sequence Diagram Code:

sequenceDiagram
    participant Alice
    participant Bob
    Alice->>Bob: Hello Bob, how are you?
    Bob-->>Alice: I am good, thank you!

Explanation:

participant defines the entities in the sequence.
->> represents a message being sent, while -->> represents a response.

4. Generating a Gantt Chart

A Gantt chart is a type of bar chart that represents a project schedule. Mermaid allows you to define tasks, durations, and dependencies.

Example Gantt Chart Code:

gantt
    title Software Development Plan
    dateFormat  YYYY-MM-DD
    section Planning
    Requirements         :done,    des1, 2023-01-01,2023-01-10
    Design               :active,  des2, 2023-01-11, 10d
    section Development
    Backend Development  :         dev1, 2023-01-21, 15d
    Frontend Development :         dev2, after dev1, 20d
    section Testing
    Integration Testing  :         test1, after dev2, 5d
    User Acceptance Test :         test2, 2023-02-15, 10d

Explanation:

gantt declares the start of a Gantt chart.
title adds a title to the chart.
dateFormat sets the date format.
Each section contains tasks, with attributes like done, active, or task dependencies (e.g., after dev1).

5. Embedding Mermaid in Documentation and Tools

a. GitHub

Mermaid diagrams can be directly embedded in GitHub markdown by enclosing them in a mermaid code block, as shown earlier. GitHub automatically renders these diagrams.

b. Visual Studio Code (VSCode)

You can use the Mermaid Markdown Preview Extension to preview Mermaid diagrams directly in VSCode.

c. Markdown Editors

Many Markdown editors like Typora, Obsidian, and Notion support Mermaid syntax for creating diagrams.

Conclusion

Mermaid is an incredibly useful tool for visualizing processes, interactions, and timelines with minimal effort. It’s easy to integrate into various platforms and offers a flexible way to create professional-looking diagrams in Markdown or HTML.

Explore more diagrams and advanced options in the Mermaid Documentation.

What You Will Learn:

1. Setting Up Mermaid

a. Use Mermaid with HTML:

b. Using Mermaid in Markdown:

2. Creating a Flowchart

Example Flowchart Code:

Explanation:

Resulting Flowchart:

3. Building a Sequence Diagram

Example Sequence Diagram Code:

Explanation:

4. Generating a Gantt Chart

Example Gantt Chart Code:

Explanation:

5. Embedding Mermaid in Documentation and Tools

a. GitHub

b. Visual Studio Code (VSCode)

c. Markdown Editors

Conclusion

Comments