What is Mermaid.js? A Beginner's Introduction to Diagrams as Code

What is Mermaid.js?

Mermaid.js is a JavaScript-based diagramming and charting tool that turns simple text definitions into rich, visual diagrams. Instead of dragging boxes and arrows around in a GUI, you write a few lines of human-readable text, and Mermaid renders the diagram for you.

Think of it as Markdown, but for diagrams. Just as Markdown lets you write formatted documents without a word processor, Mermaid lets you create flowcharts, sequence diagrams, Gantt charts, and more without a drawing tool.

A Quick Example

Here's how simple it is. This text:

graph TD
    A[Write Code] --> B[Commit]
    B --> C[Push to GitHub]
    C --> D[Deploy]

Produces a clean flowchart showing a basic deployment pipeline. No mouse dragging, no alignment headaches — just text.

Why Developers Love Mermaid.js

1. Version Control Friendly

Because diagrams are plain text, they live in your Git repository alongside your code. You can track changes, review diffs, and merge updates just like any other source file. Try doing that with a PNG exported from a drawing tool.

2. Speed of Creation

Creating a diagram in Mermaid takes seconds, not minutes. Once you learn the syntax, you can sketch out architectures, flows, and relationships faster than you could open a GUI tool. The mental model stays in text, which is where developers already live.

3. Always Up to Date

When diagrams live next to the code they describe, they're far more likely to stay current. A diagram in a README file gets updated in the same pull request that changes the architecture. Traditional diagrams in separate files or external tools tend to go stale quickly.

4. Platform Support

Mermaid diagrams render natively in GitHub, GitLab, Notion, Obsidian, Confluence (via plugins), and many other platforms. You don't need a special viewer — the platforms render them inline.

5. No Account Required

Unlike SaaS diagramming tools, Mermaid is open-source and runs in the browser. There's no sign-up, no subscription, no vendor lock-in. Your diagrams are portable text files.

What Types of Diagrams Can You Create?

Mermaid supports a wide variety of diagram types, each suited for different use cases:

Each diagram type has its own simple syntax, but they all follow the same pattern: a declaration line followed by relationships.

Getting Started with Mermaid.js

Option 1: Use a Live Editor

The fastest way to try Mermaid is with an online editor. You type on the left, see the diagram on the right. No installation needed.

Option 2: Add to Your Website

Include Mermaid in any HTML page:

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

<pre class="mermaid">
graph LR
    A --> B --> C
</pre>

Option 3: Use in Markdown

On platforms like GitHub, simply wrap your diagram in a mermaid code fence:

graph TD

A --> B

GitHub will render it automatically — no plugins needed.

Option 4: Install via npm

For programmatic use in Node.js or build tools:

npm install mermaid

Your First Flowchart

Let's build a practical example — a user login flow:

graph TD
    Start([User visits site]) --> Check{Logged in?}
    Check -- Yes --> Dashboard[Show Dashboard]
    Check -- No --> Login[Show Login Form]
    Login --> Submit[User submits credentials]
    Submit --> Validate{Valid?}
    Validate -- Yes --> Dashboard
    Validate -- No --> Error[Show Error]
    Error --> Login

This creates a complete login flow diagram with decision points, loops, and clear labels. Notice how readable the source text is — even without rendering, you can understand the flow.

Key Syntax Concepts

Nodes are defined with text in brackets:

- A[Rectangle] — standard box

- A(Rounded) — rounded corners

- A{Diamond} — decision/rhombus

- A([Stadium]) — stadium shape

- A([Circle]) — circle

Edges connect nodes:

- A --> B — arrow

- A --- B — line without arrow

- A -->|label| B — arrow with label

- A -.-> B — dotted arrow

- A ==> B — thick arrow

Direction is set on the first line:

- graph TD — top to bottom

- graph LR — left to right

- graph BT — bottom to top

- graph RL — right to left

Mermaid.js vs Traditional Tools

How does Mermaid compare to tools like Draw.io, Lucidchart, or Visio?

Mermaid wins at: speed, version control, documentation integration, automation, and cost (free).

Traditional tools win at: pixel-perfect layouts, complex custom styling, non-technical users, and presentation-ready output.

The sweet spot for Mermaid is technical documentation — README files, architecture docs, design documents, and wikis. For marketing materials or highly styled presentations, a GUI tool may be better.

Common Use Cases

1. Architecture diagrams in project READMEs
2. API flow documentation with sequence diagrams
3. Database schemas with ER diagrams
4. Sprint planning with Gantt charts
5. Decision trees for business logic
6. Onboarding docs showing system overview
7. State machines for UI components or workflows

Tips for Beginners

• Start simple. Get a basic flowchart working, then explore other diagram types.
• Use a live editor to see results instantly as you type.
• Read the official docs at [mermaid.js.org](https://mermaid.js.org) for syntax details.
• Copy examples and modify them — it's the fastest way to learn.
• Keep diagrams focused. One diagram per concept. If it's getting complex, split it.

Conclusion

Mermaid.js bridges the gap between text-based documentation and visual communication. It's fast, free, version-controllable, and increasingly supported across the platforms developers already use. Whether you're documenting an API, planning a project, or modeling a database, Mermaid lets you create professional diagrams without leaving your text editor.

Try it now in our free Mermaid Live Editor →