Mermaid Basics: Your First Diagram

In Lesson 1, you learned why diagrams-as-code matters. Now let’s write one. By the end of this lesson, you’ll have created your first Mermaid diagram and understand the syntax building blocks that every diagram type shares.

The Mermaid Live Editor

Open mermaid.live in your browser. This is your sandbox — type Mermaid code on the left, see the rendered diagram on the right, instantly.

You’ll use this throughout the course. Bookmark it.

Your First Diagram

Type this into the Live Editor:

graph TD
    A[Start] --> B[Process Data]
    B --> C{Is Valid?}
    C -->|Yes| D[Save]
    C -->|No| E[Show Error]

You just created a flowchart. Let’s break down every piece.

Core Syntax: The Four Building Blocks

Every Mermaid diagram uses the same foundation:

1. Diagram Type + Direction

The first line declares what you’re drawing and which way it flows:

graph TD    → flowchart, top to bottom
graph LR    → flowchart, left to right
sequenceDiagram  → sequence diagram (no direction needed)
classDiagram     → class diagram

Directions: TD (top-down), LR (left-right), RL (right-left), BT (bottom-top).

2. Nodes (the boxes)

Nodes are the shapes in your diagram. The shape depends on the brackets:

The letter before the brackets (A, B, C) is the node’s ID — it must be unique. The text inside the brackets is what gets displayed.

✅ Quick Check: You want to represent a database in your diagram. Which syntax would you use — DB[Users Database] or DB[(Users Database)]? (The cylinder shape [(text)] visually represents a database. The rectangle [text] would work but doesn’t give the reader the visual cue.)

3. Connections (the arrows)

Connections link nodes together:

A --> B       → Arrow (directed)
A --- B       → Line (no direction)
A -->|label| B → Arrow with text label
A -.-> B      → Dotted arrow
A ==> B       → Thick arrow

Labels on arrows are powerful — they explain the relationship: -->|sends request|, -->|returns data|, -->|on failure|.

4. Subgraphs (grouping)

Group related nodes inside a labeled box:

graph LR
    subgraph Frontend
        A[React App] --> B[API Client]
    end
    subgraph Backend
        C[Express Server] --> D[(PostgreSQL)]
    end
    B --> C

Subgraphs are how you show system boundaries — frontend vs. backend, internal vs. external, team A vs. team B.

Putting It Together: A Real Example

Here’s a user registration flow — a diagram you’d actually use in a project:

graph TD
    A[User clicks Sign Up] --> B[Show Registration Form]
    B --> C{Valid Input?}
    C -->|No| D[Show Validation Errors]
    D --> B
    C -->|Yes| E[Create Account]
    E --> F{Email Exists?}
    F -->|Yes| G[Show Duplicate Error]
    G --> B
    F -->|No| H[Send Verification Email]
    H --> I[Show Success Message]

Count the building blocks: 9 nodes, 9 connections, 2 decision diamonds, labels on the decision paths. All from plain text.

Styling Basics

You can add colors and styles. Keep it simple — readability first:

graph LR
    A[Input] --> B[Process]
    B --> C[Output]
    style A fill:#e1f5fe
    style C fill:#c8e6c9

For consistent styling across nodes, use classDef:

graph LR
    classDef primary fill:#e3f2fd,stroke:#1565c0
    classDef success fill:#e8f5e9,stroke:#2e7d32
    A[Start]:::primary --> B[Done]:::success

Don’t over-style. The default Mermaid theme is clean and professional. Add color only when it communicates meaning (success = green, error = red, warning = yellow).

✅ Quick Check: You want an arrow from node A to node B with the label “sends email.” Write the Mermaid syntax. (A -->|sends email| B — the label goes between pipe characters on the arrow syntax.)

Common Beginner Mistakes

The #1 rule: stick to ASCII characters. No smart quotes, no em dashes, no special Unicode. Mermaid’s parser is strict about this.

Key Takeaways

• Every Mermaid diagram starts with a type declaration (graph TD, sequenceDiagram, etc.)
• Nodes use bracket syntax for shapes: [] rectangle, () rounded, {} diamond, (()) circle, [()] cylinder
• Connections use arrow syntax: --> directed, --- undirected, -->|label| with text
• Subgraphs group related nodes inside labeled boundaries
• Stick to ASCII characters — smart quotes and em dashes break the parser
• Use the Mermaid Live Editor (mermaid.live) to practice and see results instantly

Up Next

In Lesson 3, we’ll go deep on flowcharts — the most versatile diagram type. You’ll learn advanced patterns: nested subgraphs, parallel flows, error handling paths, and how to model real business processes.