A Beginner's Guide to Mermaid.js

Mermaid.js is an open-source JavaScript library that turns plain text into diagrams. Instead of dragging boxes around in a GUI tool, you write a short description of what the diagram should contain, and Mermaid renders it as an SVG. If you can write Markdown, you can write Mermaid. This guide covers everything you need to go from zero to productive.

What Is Mermaid.js?

Mermaid was created by Knut Sveidqvist in 2014 to solve a simple problem: keeping diagrams in sync with code. Traditional diagramming tools produce binary files that cannot be diffed, reviewed, or version-controlled alongside source code. Mermaid takes a different approach -- diagrams are defined in plain text, so they live in the same repository, go through the same pull request process, and stay up to date with the systems they describe.

The library has grown from a simple flowchart renderer into a full diagramming toolkit supporting over a dozen diagram types. It is now one of the most-starred JavaScript visualization projects on GitHub, with native support in platforms like GitHub, GitLab, Notion, Obsidian, and Docusaurus.

Getting Started

There are several ways to start using Mermaid, depending on your needs.

Option 1: Online Editor (Fastest)

The fastest way to try Mermaid is with an online editor. Open the SimpleMermaid editor, type your diagram code on the left, and see the rendered output on the right in real time. No installation, no setup, no account required. When your diagram is ready, export it as PNG or SVG, or generate a shareable link.

Option 2: CDN (For Web Pages)

To embed Mermaid diagrams in your own website, add the library via CDN:

Mermaid scans the page for elements with the mermaid class and replaces them with rendered SVGs. That is the entire integration -- no build step, no bundler configuration.

Option 3: npm (For Projects)

For Node.js projects, install Mermaid as a dependency:

Then import and initialize it in your JavaScript:

Option 4: GitHub Markdown (Zero Setup)

GitHub renders Mermaid diagrams natively in Markdown files, issues, and pull requests. Wrap your diagram in a fenced code block with the mermaid language identifier:

When someone views the file on GitHub, they see the rendered diagram, not the source code. This makes it trivial to keep architecture diagrams in your repository.

Your First Flowchart

Let us build a flowchart step by step. Every Mermaid diagram begins with a declaration of its type.

Step 1: Declare the diagram type and direction.

flowchart tells Mermaid you want a flowchart. TD means top-down (top to bottom). Other options are LR (left to right), BT (bottom to top), and RL (right to left).

Step 2: Add nodes.

Nodes are defined with an ID followed by text in brackets. Square brackets [ ] create rectangles. Curly braces { } create diamonds (decision nodes). Round brackets ( ) create rounded rectangles.

Step 3: Connect nodes with arrows.

The --> operator draws an arrow. Text between dashes becomes the arrow label. The result is a complete CI/CD flowchart: write code, run tests, deploy if they pass, fix bugs and loop if they fail.

Supported Diagram Types

Mermaid supports a wide range of diagram types. Here is an overview of the most commonly used ones:

Each type has its own syntax, but the philosophy is the same: short, readable text that produces a clear visual. The Learn Mermaid page covers each type in depth with examples.

Styling Basics

Mermaid provides two ways to customize how your diagrams look.

Themes

Mermaid ships with built-in themes: default, dark, forest, and neutral. Set the theme during initialization:

Inline Styles

For fine-grained control, use the style directive to target individual nodes:

You can also define CSS classes and apply them to multiple nodes at once using the classDef and class directives:

Where Mermaid Is Supported

One of Mermaid's biggest advantages is its growing ecosystem of native integrations. You may already have access to Mermaid rendering without installing anything:

• GitHub -- Renders Mermaid in Markdown files, issues, PRs, and wikis.
• GitLab -- Native Mermaid support in Markdown across the platform.
• Notion -- Supports Mermaid in code blocks.
• Obsidian -- Built-in Mermaid rendering in notes.
• Docusaurus -- Mermaid plugin for documentation sites.
• Jupyter Notebooks -- Available via extensions.
• VS Code -- Preview with the Mermaid extension.
• Confluence -- Via marketplace plugins.

This broad support means your Mermaid diagrams are portable. Write them once, and they render wherever your team works.

Next Steps

You now have the foundation to start creating diagrams with Mermaid.js. Here is a roadmap for going deeper:

1. Practice with the editor. Open the SimpleMermaid editor and try each diagram type. The built-in examples cover 45+ real-world use cases.
2. Learn sequence diagrams. They are the most useful type for documenting APIs and microservice interactions. See our guide on documenting APIs with diagrams.
3. Explore state diagrams. If you build user interfaces, state diagrams for UI design will change how you think about component logic.
4. Adopt diagrams as code. Store your diagrams in version control and integrate them into your workflow. Read our article on diagrams as code workflows.

The best way to learn Mermaid is to use it. Pick a system you are working on right now, open the editor, and diagram it. You will be surprised how quickly the syntax becomes second nature.