If you've ever stared at a blank text editor trying to remember the exact syntax for a Mermaid flowchart or sequence diagram, you already know the value of a good cheat sheet. Mermaid lets you create diagrams using plain text and a simple markup language but between arrow types, node shapes, keywords, and subgraph nesting, there's a lot to keep straight. Having a reliable mermaid diagram syntax cheat sheet next to you saves time, prevents errors, and keeps your focus on the content of your diagrams rather than the formatting rules.

What Exactly Is a Mermaid Diagram Syntax Cheat Sheet?

A Mermaid diagram syntax cheat sheet is a quick-reference document that summarizes the core syntax rules for creating diagrams using Mermaid.js, the open-source text-based diagramming library. Instead of digging through full documentation every time you need to draw a class diagram or set up a Gantt chart, a cheat sheet gives you the essential keywords, patterns, and examples in a scannable format.

Think of it like a keyboard shortcut card you'd tape next to your monitor. You probably know most of the commands already, but having them listed out helps you work faster and catch mistakes before they break your diagram rendering.

Who Actually Uses Mermaid Syntax Cheat Sheets?

Mermaid diagrams show up in a wide range of workflows. Developers embed them in GitHub README files and documentation wikis. Technical writers use them to illustrate system architecture in markdown-based docs. Project managers rely on Mermaid for Gantt charts directly inside tools like Jira, Notion, or Obsidian. Students and educators use them for coursework that requires diagrams without the hassle of drag-and-drop tools.

If you work in any environment that supports markdown rendering GitHub, GitLab, Notion, Confluence (with plugins), Typora, or VS Code with preview extensions you can write Mermaid syntax inline and see the diagram render automatically. That's a big part of why a cheat sheet is so handy: you're often writing these diagrams directly in text editors, not in visual diagramming software.

What Diagram Types Can You Create with Mermaid?

Mermaid supports a growing number of diagram types. The most commonly used ones include:

  • Flowcharts Decision trees, process flows, and workflows
  • Sequence diagrams Interactions between actors or systems over time
  • Gantt charts Project timelines and scheduling
  • Class diagrams Object-oriented class structures and relationships
  • State diagrams Finite state machines and transitions
  • Entity-relationship diagrams Database schemas and relationships
  • Pie charts Simple proportional data visualization
  • Git graphs Branch and commit visualization
  • Mindmaps Hierarchical idea mapping

Each diagram type has its own syntax rules and keywords, which is exactly why a cheat sheet becomes so useful once you start mixing diagram types across different projects.

How Do You Write a Flowchart in Mermaid?

Flowcharts are the most popular diagram type in Mermaid, and they're a good starting point for understanding the syntax fundamentals.

Here's a basic example:

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

A few things to notice:

  • graph TD sets the direction TD means top-down. You can also use LR (left-right), BT (bottom-top), or RL (right-left).
  • Square brackets [] create rectangle nodes.
  • Curly braces {} create diamond shapes (commonly used for decisions).
  • Arrows --> connect nodes. You can add labels with |text| between the arrows.
  • Node IDs (like A, B, C) are internal references. The text inside brackets is what displays in the rendered diagram.

For a more detailed walkthrough of sequence diagram syntax specifically, check out our sequence diagram reference guide.

How Does Mermaid Sequence Diagram Syntax Work?

Sequence diagrams in Mermaid follow a different syntax pattern from flowcharts. They focus on showing how different participants exchange messages over time.

Here's a simple example:

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

Key syntax elements:

  • sequenceDiagram declares the diagram type.
  • ->> represents a solid arrow (synchronous message).
  • -->> represents a dashed arrow (asynchronous or response).
  • Participants are automatically created from the message definitions, or you can declare them explicitly with participant Name.
  • You can add notes using Note over Alice: some note or Note left of Bob: text.
  • Loops, conditions, and alt blocks use keywords like loop, alt, else, and opt.

How Do You Build a Gantt Chart with Mermaid?

Gantt charts in Mermaid use a keyword-driven syntax that defines tasks, durations, and dependencies. The keyword gantt starts the diagram, followed by a title, date format, and section declarations.

A basic Gantt chart looks like this:

gantt
  title Project Plan
  dateFormat YYYY-MM-DD
  section Design
  Wireframes :a1, 2024-01-01, 7d
  Mockups :a2, after a1, 5d
  section Development
  Frontend :b1, after a2, 10d
  Backend :b2, after a2, 12d

The syntax lets you define task names, start dates (or dependencies using after), and durations. For a full breakdown of Gantt chart syntax, see our Gantt chart syntax explanation.

What Are the Most Common Mermaid Syntax Mistakes?

Even experienced users run into rendering errors with Mermaid. Here are the mistakes that come up most often:

  • Missing or wrong indentation. Mermaid is sensitive to whitespace in some diagram types. Indentation inside blocks like subgraph or sequenceDiagram matters.
  • Special characters in node text. Characters like (, ), [, ], and # inside labels can break the parser. Wrap text in quotes to be safe: A["Text with (parentheses)"].
  • Using the wrong arrow syntax. Mixing up --> and ->> or using plain -> (which doesn't work) is a common issue.
  • Forgetting the diagram type declaration. Every Mermaid diagram needs a type keyword on the first line: graph, sequenceDiagram, gantt, classDiagram, etc.
  • Confusing graph with flowchart. Both work for flowcharts, but flowchart (newer syntax) supports additional features. Stick with one or the other to avoid confusion.
  • Overlapping node IDs in complex diagrams. When your diagram grows, reusing IDs or forgetting to define connections leads to orphaned nodes.

Where Can You Use Mermaid Diagrams?

Mermaid's text-based format makes it easy to embed diagrams almost anywhere that supports markdown or HTML rendering:

  • GitHub and GitLab Mermaid blocks render natively in markdown files and pull request descriptions.
  • Notion and Obsidian Both support Mermaid code blocks for inline diagrams.
  • VS Code Extensions like "Markdown Preview Mermaid Support" render diagrams in the editor preview.
  • Confluence Plugins like "Mermaid Diagrams for Confluence" add support.
  • Static site generators Tools like Hugo, Jekyll, and Docusaurus can render Mermaid with the right plugins.
  • Standalone HTML pages Include the Mermaid.js script via CDN and write diagrams directly in your markup.

This broad compatibility is one reason Mermaid has become the go-to diagram-as-code tool. Unlike images, your diagrams live as version-controlled text, so you can track changes in Git just like any other file.

What Tips Help You Write Mermaid Syntax More Efficiently?

  1. Use the Mermaid Live Editor. The official live editor lets you write syntax on the left and see the rendered diagram on the right in real time. It's the fastest way to debug syntax errors.
  2. Start simple, then add detail. Write a minimal diagram first just nodes and connections then layer in styles, subgraphs, and labels.
  3. Use subgraph to organize complex flowcharts. Grouping related nodes into subgraphs makes large diagrams much easier to read and maintain.
  4. Define styles with classDef. Instead of styling each node individually, define reusable classes: classDef highlight fill:#f96,stroke:#333.
  5. Keep a local cheat sheet file. A markdown file in your project's docs folder with your most-used syntax patterns saves you from searching the web every time.
  6. Test rendering across platforms. A diagram that renders in the live editor might look different in GitHub or Notion due to version differences. Always verify in your target environment.

For a broader reference covering multiple diagram types, bookmark our full mermaid syntax cheat sheet.

Quick Syntax Reference: Node Shapes You Should Know

One of the trickiest parts of Mermaid flowcharts is remembering which bracket syntax creates which shape:

  • A[Text] Rectangle (default)
  • A(Text) Rounded rectangle
  • A([Text]) Stadium / pill shape
  • A[[Text]] Subroutine shape
  • A((Text)) Circle
  • A>Text] Flag / asymmetric shape
  • A{Text} Diamond (decision)
  • A{{Text}} Hexagon
  • A[/Text/] Parallelogram
  • A[\Text\] Parallelogram (alt direction)
  • A[/Text\] Trapezoid
  • A[\Text/] Trapezoid (alt direction)

When in doubt, use the cheat sheet reference to look up the exact bracket pattern you need.

Your Next Steps

Ready to put this reference into practice? Here's a checklist to get you going:

  • Open the Mermaid Live Editor and try writing a basic flowchart with three nodes and a decision diamond.
  • Write a sequence diagram with at least two participants and a loop block.
  • Embed a Mermaid code block in a GitHub README or your note-taking app and confirm it renders correctly.
  • Save the node shape list above in a local file so you can reference it without opening a browser.
  • Try building a Gantt chart for a real or mock project timeline to test your understanding of task syntax.
  • Pick one diagram type you use most often and memorize its opening keyword and core syntax rules that alone will cover 80% of your daily use.