T01: What is Mermaid

What is Mermaid

1.1 Definition

Mermaid is a JavaScript-based diagramming and charting tool that allows you to create diagrams using plain text syntax. Instead of drawing shapes manually in a GUI tool, you describe the structure of a diagram using a declarative, text-based language, and Mermaid renders it into a visual diagram.

Mermaid follows the Diagram-as-Code paradigm — similar to Infrastructure-as-Code or Documentation-as-Code — where diagrams are version-controlled, diffable, and reproducible.

In simple terms:

Write structured text → Generate professional diagrams.

---

1.2 Why Mermaid Exists

Traditional diagram tools (Visio, draw.io, Lucidchart) are:

• Manual

• Hard to version control

• Difficult to diff in Git

• Not automation-friendly

Mermaid solves this by:

• Keeping diagrams in plain text

• Making them Git-friendly

• Allowing automation in CI/CD pipelines

• Integrating directly into Markdown documentation

If you can write structured text, you can generate diagrams.

---

1.3 Where Mermaid Is Used

Mermaid is commonly used in:

• Technical documentation

• Software architecture design

• API interaction diagrams

• Database schema documentation

• DevOps workflows

• Project planning (Gantt charts)

It is supported in:

• GitHub Markdown

• GitLab

• Notion

• Obsidian

• Docusaurus

• MkDocs

• VS Code extensions

• Static site generators

---

1.4 How Mermaid Works

Mermaid works in three steps:

1. You write Mermaid syntax inside a code block.

2. The Mermaid engine parses the syntax.

3. It renders the diagram as SVG.

Example structure in Markdown:

```mermaid
flowchart TD
    A[Start] --> B[Process]
    B --> C[End]
```

The keyword after the triple backticks (mermaid) tells the renderer to interpret the content as Mermaid syntax.

---

1.5 Your First Mermaid Diagram (Hands-On)

Let’s build a simple flowchart.

Example 1: Basic Flowchart

flowchart TD
    A[Start] --> B[Write Mermaid Code]
    B --> C[Render Diagram]
    C --> D[Visual Output]

Explanation:

• flowchart → Diagram type

• TD → Top-Down direction

• A, B, C, D → Node identifiers

• [Text] → Node label

• --> → Arrow connection

---

Example 2: Changing Direction

flowchart LR
    A[Client] --> B[Server]
    B --> C[Database]

Here:

• LR means Left-to-Right layout.

Other directions:

• TD → Top to Down

• BT → Bottom to Top

• RL → Right to Left

---

Example 3: Different Node Shapes

flowchart TD
    A[Rectangle]
    B(Rounded)
    C((Circle))
    D{Decision}
    E[[Subroutine]]

    A --> B
    B --> C
    C --> D
    D --> E

Common shapes:

• [Text] → Rectangle

• (Text) → Rounded

• ((Text)) → Circle

• {Text} → Diamond (Decision)

• [[Text]] → Subroutine

---

1.6 Mermaid as Diagram-as-Code

Because Mermaid is plain text:

• It can be stored in Git

• You can review changes via pull requests

• You can auto-generate diagrams during documentation builds

• You can template diagrams

Example Git diff:

- A --> B
+ A --> C

This is impossible with binary diagram formats.

---

1.7 Supported Diagram Types (Overview)

Mermaid supports multiple diagram types, including:

• Flowcharts

• Sequence diagrams

• Class diagrams

• State diagrams

• Gantt charts

• Entity Relationship diagrams

• User Journey diagrams

• Git graphs

Each diagram starts with a specific keyword such as:

flowchart
sequenceDiagram
classDiagram
stateDiagram
gantt

You will explore these in later chapters.

---

1.8 Advantages of Mermaid

1. Text-Based

Readable and maintainable.

2. Version Control Friendly

Works naturally with Git.

3. Automation Ready

Can be generated programmatically.

4. Lightweight

No heavy GUI required.

5. Open Ecosystem

Works across many platforms and documentation systems.

---

1.9 Limitations

• Less flexible than manual drawing tools for highly custom visuals.

• Complex diagrams can become verbose.

• Layout control is limited compared to GUI-based editors.

However, for technical documentation and structured diagrams, Mermaid is highly efficient.

---

1.10 Practical Exercise

Try writing the following diagram in your Markdown editor:

flowchart TD
    A[User] --> B[Login]
    B --> C{Valid Credentials?}
    C -->|Yes| D[Dashboard]
    C -->|No| E[Error Message]
    E --> B

Task:

1. Change the direction to Left-to-Right.

2. Add a new node called "Logout".

3. Connect Dashboard to Logout.

This small exercise will help you understand syntax mechanics.

---

Summary

Mermaid is a text-based diagramming tool that enables you to define diagrams using structured syntax. It aligns with modern engineering practices by making diagrams version-controlled, automatable, and reproducible.

In the next chapter, you will dive deep into Flowcharts, the most widely used Mermaid diagram type.

---