Learn Mermaid

Quick Start: This guide gets you writing Mermaid diagrams that render on GitHub in about 15 minutes. Learn the two diagram types that cover most real work, then build a deployment pipeline diagram you can drop into any README.

What You’ll Learn

• What is Mermaid, and what problem does it solve?
• What are the use cases for Mermaid?
• When is Mermaid not the right tool?
• Which two diagram types cover most real work?
• How do you build a pipeline diagram and publish it on GitHub?
• Where can you go to learn more about Mermaid?

The Basics

Mermaid is an open-source tool that turns short text descriptions into diagrams. Type A --> B and you get two boxes connected by an arrow. Knut Sveidqvist created it in 2014 so diagrams could live where code lives: in plain text, in version control, reviewed in pull requests like everything else.

That placement is the point. A diagram exported from a drawing tool goes stale the day after you paste it into a wiki. A Mermaid diagram sits next to the code it describes, diffs cleanly, and renders natively in GitHub, GitLab, VS Code, Obsidian, and Hugo.

Mermaid supports more than 20 diagram types. You need two of them: flowcharts and sequence diagrams. Those two, plus subgraphs for grouping, cover most diagrams a working engineer draws. This guide teaches exactly that and leaves class diagrams, Gantt charts, and entity relationship diagrams to the resources in the launch pad below.

Primary Use Cases

• Architecture and process diagrams in READMEs, design docs, and wikis.
• Sequence diagrams that show how services, APIs, and users interact.
• Documentation that must stay current, because the diagram source is reviewable text.

Less Suitable Use Cases

• Pixel-perfect graphics for slides or marketing. Use Figma or Canva.
• Diagrams with 50+ nodes. Mermaid’s automatic layout turns large graphs into spaghetti. Split the diagram or use draw.io.
• Freeform whiteboarding where you control exact positions. Mermaid decides the layout for you.

When to Use Mermaid

Use Mermaid when the diagram documents software and belongs in version control. Accept the trade-off: you give up precise visual control and get diagrams that are cheap to create, easy to review, and likely to stay accurate. When exact layout matters more than maintenance, pick a drawing tool instead.

The 20% That Does 80%

Two diagram types and one grouping construct. Everything below is copyable.

Flowcharts

A flowchart starts with flowchart TB (top to bottom), then lists nodes and arrows. Node shape carries meaning: square brackets make a rectangle for a step, curly braces make a diamond for a decision.

flowchart TB
    A[Commit code] --> B{Tests pass?}
    B -->|Yes| C[Deploy to staging]
    B -->|No| D[Fix the build]
    D --> A

That renders as:

What you get: Each line declares a node or a connection. A is an internal ID, the bracketed text is the label, and -->|Yes| labels the arrow. Other useful shapes: (Rounded) for start and end points, [(Database)] for data stores.

Sequence Diagrams

Sequence diagrams show who talks to whom, in what order. Declare participants, then list messages. ->> is a solid arrow for a request, and -->> is a dashed arrow for a response.

sequenceDiagram
    participant U as User
    participant A as API
    participant D as Database
    U->>A: POST /login
    A->>D: Look up user
    D-->>A: User record
    A-->>U: 200 OK with token

That renders as:

What you get: A timeline that reads top to bottom, with one vertical line per participant. This is the fastest way to document an API interaction or debug a distributed flow.

Subgraphs

Subgraphs group related nodes inside a flowchart, which keeps medium-sized diagrams readable.

flowchart TB
    A[Commit code] --> B{Tests pass?}
    B -->|Yes| C[Build image]

    subgraph delivery [Delivery]
        C --> S[Deploy to staging]
        S --> P[Deploy to production]
    end

What you get: A labeled box around the delivery steps. Readers see the pipeline stages at a glance instead of parsing individual nodes.

Where Diagrams Render

• GitHub and GitLab: put the diagram in a fenced code block with the language set to mermaid. It renders automatically in READMEs, issues, and pull requests. See GitHub’s guide to creating diagrams.
• VS Code: install the Markdown Preview Mermaid Support extension to render diagrams in Markdown preview.
• Obsidian and Notion: both render Mermaid blocks natively.
• Anywhere else: the Mermaid Live Editor renders any diagram and exports PNG or SVG.

Build Something: A Deployment Pipeline Diagram

Build a real diagram and publish it. This takes about 15 minutes.

Prerequisites

You’ll need:

• A web browser.
• A GitHub account (only for the final step; skip it if you just want the diagram).
• About 15 minutes.

Step 1: Render Your First Diagram

Open the Mermaid Live Editor. Delete the sample code in the left pane and paste this:

flowchart TB
    A[Commit code] --> B[Run tests]
    B --> C[Build image]
    C --> D[Deploy]

The right pane immediately shows a four-box pipeline flowing top to bottom.

What you learned: The editor re-renders on every keystroke, which makes it the fastest place to iterate on a diagram.

Step 2: Add a Decision

Real pipelines branch. Replace the code with this:

flowchart TB
    A[Commit code] --> B{Tests pass?}
    B -->|No| E[Fix and recommit]
    E --> A
    B -->|Yes| C[Build image]
    C --> D[Deploy]

The diagram now shows a diamond after the commit step, with a failure loop back to the start.

What you learned: Curly braces create decisions, -->|label| names each branch, and arrows can point back to earlier nodes.

Step 3: Group the Delivery Stages

Split deployment into staging and production, grouped in a subgraph:

flowchart TB
    A[Commit code] --> B{Tests pass?}
    B -->|No| E[Fix and recommit]
    E --> A
    B -->|Yes| C[Build image]

    subgraph delivery [Delivery]
        C --> S[Deploy to staging]
        S --> P[Deploy to production]
    end

The finished diagram looks like this:

What you learned: Subgraphs draw a labeled boundary without changing the flow. Use them for pipeline stages, service boundaries, or network zones.

Step 4: Publish It on GitHub

Open any repository README (or create a new repository), edit the file, and add your diagram inside a fenced code block. The fence language must be exactly mermaid:

```mermaid
flowchart TB
    A[Commit code] --> B{Tests pass?}
    B -->|No| E[Fix and recommit]
    E --> A
    B -->|Yes| C[Build image]

    subgraph delivery [Delivery]
        C --> S[Deploy to staging]
        S --> P[Deploy to production]
    end
```

Commit the change and view the README. GitHub renders the diagram in place.

What you learned: The diagram is now versioned. The next change to the pipeline goes through the same pull request review as the code that implements it.

Troubleshooting

“Syntax error in text”

Usually a reserved word or unquoted special characters. Never name a node end in lowercase, because it terminates subgraphs; use End or a different ID. Wrap labels containing parentheses or brackets in quotes: A["Retry (max 3)"].

The diagram shows as plain code on GitHub

The fence language must be exactly mermaid, lowercase, with no extra text on the fence line. Check for a typo like mermaidjs.

It renders in the Live Editor but errors on GitHub

GitHub pins an older Mermaid version than the Live Editor runs. Newly released syntax can fail. Stick to the constructs in this guide, which are stable, or check the error message for the unsupported keyword.

The layout sprawls sideways or overlaps

Prefer flowchart TB over LR for anything with more than a few nodes. If the diagram is still messy, that is Mermaid telling you the diagram is too big: split it into one diagram per concern.

Learn Mermaid: Beyond the Basics

You’ve covered the essentials. Here’s a curated learning track to go deeper: start with a video or the podcast, then pick a book to master the remaining diagram types.

📹 Video

• Mastering Mermaid.js on Udemy, a full course covering flowcharts, mind maps, entity relationship diagrams, and pie charts.
• The official Mermaid tutorials list, which collects community video walkthroughs of the Live Editor and core diagram types.

🔊 Audio

• Open Core Open Source with Mermaid Chart’s Knut Sveidqvist on Hanselminutes, where Mermaid’s creator tells the project’s origin story.
• Open Source Diagramming and Charting with Mermaid Chart on the Open Source Startup Podcast, on the journey from side project to company.

📚 Books

• The Official Guide to Mermaid.js by Knut Sveidqvist and Ashish Jain, written by the creator; the reference for every diagram type.
• Creating Software with Modern Diagramming Techniques by Ashley Peacock, for engineers who want diagrams in their daily workflow. I recommend starting here; it teaches Mermaid through real software design scenarios.

🌐 Online

• The Mermaid documentation, the syntax reference for all diagram types.
• The Mermaid Live Editor, the fastest place to draft and export diagrams.
• GitHub’s guide to creating diagrams, for rendering Mermaid in READMEs, issues, and pull requests.
• freeCodeCamp’s Mermaid flowchart guide, a free written tutorial that goes deeper on flowchart syntax.

Related Content

• How Do I Identify Software Use Cases, which pairs use case analysis with diagrams.
• How Do I Create a Software Ontology, where Mermaid keeps shared definitions in version control.
• How Do I Decode Software Deployments, which maps deployment footprints with diagrams.