🧜‍♀️ Learning Mermaid: A Complete Tutorial for Diagram Creation

What Is Mermaid?

Mermaid is a JavaScript library that turns Markdown-inspired text into diagrams. You describe the nodes (the boxes) and the relationships (the arrows) in a simple syntax, and Mermaid draws and lays them out automatically. It's the same idea as Markdown itself: write plain text, get a formatted result — except the result is a chart instead of a heading.

Think of Mermaid syntax like a recipe. A recipe lists ingredients and how they combine; a Mermaid diagram lists elements and how they connect. The first word — flowchart, sequenceDiagram, erDiagram — is you choosing which dish you're making, and each has its own rules.

Here is the smallest possible flowchart. This one renders:

Adding Mermaid to a Page

There are two common ways to get Mermaid running.

Option 1: The CDN (fastest to try)

<script type="module">
    import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs';
    mermaid.initialize({ startOnLoad: true });
</script>

Option 2: NPM (for real applications)

# Install it as a dependency
npm install mermaid

import mermaid from "mermaid";
mermaid.initialize({ startOnLoad: true });

Where the diagram goes

Put your diagram text inside an element with the class mermaid. On page load, Mermaid finds every such element and renders it.

<div class="mermaid">
    graph TD
        A[Start] --> B[Finish]
</div>

In Markdown files on GitHub or GitLab, you don't need any of the setup — just a fenced code block tagged mermaid:

```mermaid
graph LR
    A[Idea] --> B[Diagram]
```

Flowcharts

Flowcharts are the workhorse: processes, decision trees, architectures. A flowchart is just nodes joined by arrows.

Node shapes

The brackets around a node's text choose its shape:

flowchart TD
    A[Rectangle]
    B(Rounded)
    C([Stadium])
    D[[Subroutine]]
    E[(Database)]
    F((Circle))
    G{Decision}
    H{{Hexagon}}

Arrows and labels

flowchart LR
    A[Solid arrow] --> B[Node]
    C[Dotted] -.-> D[Node]
    E[Thick] ==> F[Node]
    G[Labeled] -->|yes| H[Node]

Real example: a login flow

Decisions use the diamond shape {...}, and the arrow labels carry the branch conditions.

Grouping with subgraphs

A subgraph draws a labeled box around related nodes — great for showing layers or services.

Sequence Diagrams

Sequence diagrams show messages passing between participants over time. They're ideal for API calls and service-to-service communication. Time flows downward; each arrow is a message.

Basic syntax

sequenceDiagram
    participant A as Alice
    participant B as Bob
    A->>B: Hello Bob how are you
    B->>A: I am good thanks
    A->>B: Great to hear

Real example: API authentication

alt and else draw a labeled box for a branch. Notice the message text is plain prose — that's a hard rule, explained below.

Class Diagrams

Class diagrams describe object-oriented structure: classes, their attributes and methods, and how they relate. They're the blueprint before the code.

Basic syntax

classDiagram
    class Animal {
        +String name
        +int age
        +makeSound() void
    }
    class Dog {
        +String breed
        +fetch() void
    }
    Animal <|-- Dog

Relationship types

Real example: an e-commerce model

State Diagrams

State diagrams model the states a system can be in and the events that move it between them — perfect for order lifecycles, UI flows, and any finite-state machine. Use stateDiagram-v2; [*] marks the start and end.

Basic syntax

stateDiagram-v2
    [*] --> Idle
    Idle --> Processing: Start task
    Processing --> Complete: Task finished
    Processing --> Failed: Error thrown
    Complete --> [*]
    Failed --> Idle: Reset

Real example: an order's lifecycle

ER Diagrams

Entity-relationship diagrams describe a database's structure: the tables (entities), their columns (attributes), and how they relate. They're the plan you draw before writing a single CREATE TABLE.

Basic syntax

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE_ITEM : contains
    CUSTOMER {
        string name
        string email
    }
    ORDER {
        int orderNumber
        date orderDate
    }

Reading the crow's-foot notation

Real example: a blog database

Git Graphs

A gitGraph visualizes branches, commits, and merges — a great way to teach a branching strategy or document a release history.

gitGraph
    commit id: "init"
    branch feature
    checkout feature
    commit id: "add form"
    commit id: "add tests"
    checkout main
    merge feature
    commit id: "release"

Rules That Keep Diagrams Rendering

Most "my diagram is blank" problems come from a small set of syntax traps. Internalize these five and your diagrams will render the first time.

When a diagram won't render, paste it into the Mermaid Live Editor. It shows the exact parse error and line number, which turns a mysterious blank box into a one-minute fix.

Practice & Quiz

flowchart TD
    start[Begin] --> load[readFile(config)]
    load --> end[Stop]

flowchart TD
    start[Begin] --> load["readFile(config)"]
    load --> done[Stop]

sequenceDiagram
    participant User
    participant FE as Frontend
    participant BE as Backend
    User->>FE: Enter credentials
    FE->>BE: Submit login request
    alt Credentials are valid
        BE->>FE: Return session token
        FE->>User: Show dashboard
    else Credentials are invalid
        BE->>FE: Return an error
        FE->>User: Show error message
    end

Best Practices & Pitfalls

✅ Do

• Keep each diagram focused — split a sprawling one into several smaller views
• Quote any label containing parentheses, colons, or other punctuation
• Use consistent, descriptive node ids and labels
• Store diagrams next to the code they describe so they stay in sync
• Test a tricky diagram in the Mermaid Live Editor before committing

❌ Don't

• Name a flowchart node end — it's reserved and can blank the diagram
• Put ;, (), ==, or ? in sequence-diagram message text
• Hard-code fill:#hex colors that become unreadable in dark mode
• Cram thirty nodes into one chart — nobody can read it
• Let diagrams rot — update them when the system changes

Summary

📚 Additional Resources

• Mermaid — official documentation
• Mermaid Live Editor — try and debug diagrams
• Mermaid — getting started guide

🚀 What's Next?

You've been rendering diagrams in the browser; next you'll master the environment where you'll run most of your backend tools. Up next: the Ubuntu Command Line Interface — navigating, managing files, permissions, pipes, and enough shell to be dangerous in the best way.