Mermaid Diagram Syntax Guide: a Complete Tutorial for Beginners

If you've ever needed to explain a system, workflow, or database structure to someone else and a picture would do it better than words Mermaid diagrams are one of the fastest ways to create that picture using plain text. The syntax is simple once you learn the patterns, but getting started can feel confusing without a clear reference. This guide walks you through the core Mermaid diagram syntax so you can start building diagrams right away.

What is Mermaid diagram syntax?

Mermaid diagram syntax is a lightweight, text-based markup language that lets you generate diagrams from written code. Instead of dragging and dropping shapes in a visual editor, you write short, structured text that Mermaid renders into flowcharts, sequence diagrams, Gantt charts, class diagrams, and more.

Mermaid was created by Knut Sveidqvist and is now widely supported on platforms like GitHub, GitLab, Notion, Obsidian, and many documentation tools. Because diagrams live as code, they're version-controllable, easy to update, and don't require any design software.

Each diagram type has its own keyword that starts the definition. For example, graph or flowchart begins a flowchart, while sequenceDiagram starts a sequence diagram. From there, you define nodes, connections, and optional styling using a consistent set of rules.

How do you write a basic Mermaid flowchart?

Flowcharts are the most common diagram type in Mermaid. The basic structure looks like this:

graph TD This declares the diagram direction. TD means top-down. You can also use LR (left to right), BT (bottom to top), or RL (right to left).

After the direction declaration, you define nodes and the arrows connecting them. Nodes are identified by an ID and can have text labels inside square brackets, parentheses, or other shapes:

A[Square box] rectangular node
B(Rounded box) rounded rectangle
C{Diamond shape} decision diamond
D((Circle)) circular node
E[[Subroutine]] double-bordered rectangle

Arrows use simple connectors:

A --> B arrow with no label
A -->|Yes| B arrow with a text label
A --- B line with no arrowhead
A -.-> B dotted arrow
A ==> B thick arrow

If you're looking for more detailed flowchart patterns and working examples, our flowchart code examples page has copy-paste snippets for common use cases.

How do you create a sequence diagram in Mermaid?

Sequence diagrams show how different actors or systems exchange messages over time. They're useful for documenting API calls, authentication flows, or any back-and-forth process.

A sequence diagram starts with the keyword sequenceDiagram. You define participants and then describe messages between them using arrows:

Alice->>Bob: Hello, Bob sends a solid arrow from Alice to Bob. Bob-->>Alice: Hi, Alice sends a dashed arrow in response. Double arrows (>> and -->>>) create open arrowheads, while single arrows create filled ones.

You can also add:

Note over Alice,Bob: This is a note adds annotations
Alice->>Bob: Request followed by activate Bob / deactivate Bob shows processing time with activation boxes
alt, else, opt, and loop blocks for conditional and repeated interactions

What other diagram types does Mermaid support?

Mermaid goes well beyond flowcharts and sequence diagrams. Here's a quick overview of the other types you can build with the syntax:

Gantt charts Use the gantt keyword to define tasks, dates, and dependencies. Useful for project timelines.
Class diagrams Start with classDiagram to map out object-oriented structures, including inheritance, composition, and interfaces.
State diagrams Use stateDiagram-v2 to show how an object transitions between states based on events.
Entity-relationship diagrams Begin with erDiagram to model database schemas with tables, columns, and relationships.
Pie charts Use the pie keyword with labeled data to create simple pie charts.
User journey maps Start with journey to chart user experiences across touchpoints.
Git graphs Use gitGraph to visualize branching and merging in a repository.

Each diagram type has its own set of syntax rules, but they all share the same approach: a keyword to declare the type, followed by structured lines that define elements and relationships.

How do you style Mermaid diagrams?

Mermaid provides several ways to change the look of your diagrams without leaving the text editor.

Inline styles

You can apply styles directly to nodes using the style keyword followed by the node ID and CSS properties. For example, style A fill:#f9f,stroke:#333 changes the fill and border of node A.

Themes

Mermaid supports built-in themes: default, forest, dark, and neutral. You set a theme in the initialization configuration or in your rendering tool's settings.

Class definitions

Instead of styling each node individually, you can define reusable CSS-like classes with classDef and then apply them with class:

classDef important fill:#ff9999,stroke:#cc0000

class A,B important

This keeps your diagrams cleaner when you have many nodes sharing the same look.

What are the most common mistakes when writing Mermaid syntax?

If your diagram won't render, here are the things most people get wrong:

Missing or wrong arrows Mermaid is picky about arrow syntax. A single dash versus a double dash changes the arrow type. Double-check your connector characters.
Special characters in labels Parentheses, brackets, and quotation marks inside node text can break parsing. Wrap labels in quotes when they contain special characters: A["Node (example)"].
Wrong indentation or line breaks Mermaid expects each statement on its own line in most editors. Some Markdown parsers also struggle with blank lines inside diagram blocks.
Forgetting the diagram type keyword Every diagram needs its opening keyword (graph TD, sequenceDiagram, etc.). Without it, nothing renders.
Using node IDs that start with numbers Node identifiers should begin with a letter or underscore, not a digit.
Undefined participants in sequence diagrams If you reference a participant only in a message line without declaring them first, Mermaid will create them automatically, but you lose control over their display order.

For a broader walkthrough that covers both syntax basics and tooling setup, see our Mermaid diagram tutorial.

Where can you preview and test Mermaid diagrams?

You don't need to install anything to try Mermaid syntax. The Mermaid Live Editor runs entirely in your browser. Type your code on the left, and the rendered diagram appears on the right instantly.

Beyond the live editor, there are solid options depending on your workflow:

VS Code The "Mermaid Markdown Syntax Highlighting" and "Markdown Preview Mermaid Support" extensions let you preview diagrams inside your editor.
GitHub and GitLab Both render Mermaid code blocks in Markdown files and pull request descriptions automatically.
Obsidian Native Mermaid support inside code blocks, which is popular among developers who keep notes in Markdown.
Notion Has a Mermaid block for embedding diagrams in documentation pages.

If you want to compare different editors, rendering options, and plugin setups, our page on the best Mermaid diagram tools for developers covers the main choices.

When should you use Mermaid instead of a visual diagramming tool?

Mermaid works best when your diagrams live alongside code and documentation. If your team tracks architecture decisions in a Git repo, documents APIs in Markdown, or writes READMEs with embedded visuals, Mermaid keeps everything in one place.

It's less ideal when you need pixel-perfect control over layout, complex custom graphics, or hand-drawn aesthetics. Tools like Figma, draw.io, or Lucidchart handle those better. The right choice depends on what matters more: editability and version control, or visual polish and flexibility.

Mermaid also shines for diagrams that change frequently. Updating a ten-line text block is faster than reopening a visual editor, finding the right shape, and redragging connections.

Quick-start checklist for your first Mermaid diagram

Pick your diagram type Choose between flowchart, sequence, class, ER, Gantt, or others based on what you need to show.
Write the opening keyword Start with graph TD, sequenceDiagram, classDiagram, or the appropriate type keyword.
Define your elements List nodes, participants, classes, or tasks with clear IDs and labels.
Connect them Use the correct arrow syntax to show relationships or message flow.
Add labels where needed Label decision branches, message types, or relationship lines for clarity.
Test in the live editor Paste your code at mermaid.live to catch syntax errors before committing.
Apply styling if needed Use style, classDef, or a theme to improve readability.
Commit and iterate Drop the diagram into your Markdown file, push to your repo, and update it whenever the system changes.