Mermaid Diagram Syntax: a Beginner's Guide to Writing Diagrams

If you've ever tried to explain a process, system, or workflow to someone and wished you had a diagram to back it up, you already understand why learning mermaid diagram syntax matters. Mermaid is a lightweight markup language that lets you create diagrams using plain text. No dragging shapes around. No expensive software. Just text that turns into visuals. For beginners, the syntax can look strange at first but once you learn a few patterns, you'll be diagramming in minutes.

What Is Mermaid Diagram Syntax?

Mermaid diagram syntax is a simple, text-based format used to generate diagrams. Instead of drawing boxes and arrows with a mouse, you write short lines of code that describe your diagram's structure. A parser then converts that text into an image like a flowchart, sequence diagram, Gantt chart, or class diagram.

The syntax uses keywords, arrows, and indentation to define relationships between elements. Think of it like writing an outline that magically becomes a picture.

You can read the official Mermaid documentation for the full language specification, but the basics below will get you started fast.

Why Would Someone Use Mermaid Instead of a Drawing Tool?

There are a few practical reasons developers, technical writers, and project managers reach for mermaid syntax:

It lives in your files. Mermaid diagrams live alongside your code or documentation in plain text. No binary files to manage.
It's version-controllable. You can track changes to diagrams in Git just like code.
It's fast. Once you know the syntax, creating a diagram takes seconds, not minutes.
It works in many tools. GitHub, GitLab, Notion, Obsidian, Confluence, and many static site generators support mermaid rendering out of the box.

How Does the Basic Mermaid Syntax Work?

Every mermaid diagram starts with a diagram type declaration. This tells the renderer what kind of diagram you're building. Here's the structure:

The first line declares the diagram type. Lines after that define nodes and connections. The syntax varies slightly depending on the diagram type, but the pattern is consistent: declare the type, then describe the structure.

Flowchart Syntax

Flowcharts are the most common mermaid diagram. You start with graph TD (top-down) or graph LR (left-right), then define nodes and connections.

Here's a simple example:

graph TD A[Start] --> B{Is it working?} B -->|Yes| C[Great] B -->|No| D[Fix it] D --> B

Notice how nodes are defined inline. Square brackets [ ] make a rectangle, curly braces { } make a diamond (for decisions), and parentheses ( ) make rounded shapes. The arrows --> connect them.

For a deeper dive into flowchart markup, including annotation tips, check out our flowchart scripting examples with annotations.

Sequence Diagram Syntax

Sequence diagrams show interactions between actors over time. They're useful for documenting API calls, user flows, or any back-and-forth process.

Start with sequenceDiagram, then list participants and messages:

sequenceDiagram Alice->>Bob: Hello Bob Bob-->>Alice: Hi Alice Alice->>Bob: How are you?

A single arrow ->> is a solid line. A dashed arrow -->> is a dashed response line. The text after the colon is the message.

Gantt Chart Syntax

Gantt charts in mermaid help you visualize project timelines using plain text. You declare gantt, set a title and date format, then list tasks with their durations.

gantt title Project Plan dateFormat YYYY-MM-DD section Planning Research :a1, 2024-01-01, 7d Design :a2, after a1, 5d

For more on Gantt chart specifics and scripting patterns, see our Gantt chart scripting reference.

Class Diagram Syntax

Class diagrams describe object structures in software. They use a syntax that defines classes with attributes and methods, plus relationships like inheritance and composition.

classDiagram class Animal Animal : +String name Animal : +makeSound() Dog --|> Animal

If you're working with object-oriented systems, our class diagram step-by-step guide walks through the full syntax.

What Are the Common Mistakes Beginners Make?

When you're starting out, a few predictable issues trip people up. Here's what to watch for:

Forgetting the diagram type on line one. Every mermaid diagram needs a type declaration at the top graph TD, sequenceDiagram, gantt, etc. Without it, nothing renders.
Using special characters in node text without quotes. If your node label contains parentheses, brackets, or other reserved characters, wrap the text in quotes: A["Label (with parens)"].
Inconsistent indentation. Mermaid is less strict than Python, but indentation helps keep your diagram readable and avoids rendering issues in some parsers.
Arrow syntax errors. A common mix-up is using a single dash instead of double. -> won't work you need --> for flowcharts.
Forgetting the colon in sequence diagram messages. The message text must follow a colon after the arrow: A->>B: message.

Where Can You Write and Preview Mermaid Diagrams?

You don't need to install anything to start. The Mermaid Live Editor lets you type syntax on the left and see the rendered diagram on the right. It's the fastest way to experiment and learn.

Other places you can write mermaid syntax include:

GitHub and GitLab Both render mermaid code blocks in markdown files and pull request comments.
VS Code Install the "Mermaid Markdown Syntax Highlighting" extension or the "Mermaid Preview" extension.
Obsidian Native mermaid support inside fenced code blocks.
Notion Use the mermaid code block type to embed diagrams directly in pages.

What Tips Help You Learn Mermaid Syntax Faster?

Start with flowcharts. They're the most visual and intuitive diagram type. Once you're comfortable, branching into other types gets easier.
Use the live editor constantly. Type something, see it render, adjust, repeat. This feedback loop is the fastest way to internalize the syntax.
Copy and modify existing diagrams. Find examples in the docs or on GitHub, paste them, and start changing labels and connections. Reverse-engineering teaches faster than reading specs.
Keep diagrams small while learning. A three-to-five node flowchart is plenty to practice with. Don't try to diagram your entire system architecture on day one.
Learn the arrow types once. Solid, dotted, thick, and labeled arrows follow simple patterns. Memorize them early they apply across most diagram types.

What Should You Practice Next?

Once you've got the basics of flowchart syntax down, here's a practical progression:

Build a flowchart for a real process you use daily. Even something like "making coffee" forces you to think about decisions, branches, and endpoints.
Try a sequence diagram for an API interaction. Map out a login flow or a webhook callback between two services.
Create a Gantt chart for a current project. List real tasks with realistic durations and dependencies.
Diagram a code structure with a class diagram. Pick a small module or component and map its classes and relationships.

Quick-Start Checklist

✅ Open the Mermaid Live Editor
✅ Type graph TD on the first line
✅ Add three connected nodes using --> arrows
✅ Wrap any label with special characters in quotes
✅ Try switching TD to LR and see how the layout changes
✅ Add a diamond-shaped decision node with { } syntax
✅ Export or copy the diagram into your documentation tool

Start small, experiment in the live editor, and build up to more complex diagram types as your confidence grows. The syntax rewards practice and once it clicks, you'll wonder why you ever opened a drag-and-drop diagram tool.