Mermaid is a JavaScript-based diagramming tool that renders diagrams from a text-based syntax. If you've ever struggled with clunky drag-and-drop diagram editors or spent hours updating visuals after a code change, the Mermaid diagram language specification offers a different approach: you write diagrams using plain text, and a rendering engine turns them into SVGs, PNGs, or live visuals. This matters because diagrams-as-code are version-controllable, easy to update, and readable by both humans and machines.

The specification defines every rule Mermaid follows from how you declare a flowchart node to how you wire up a sequence diagram. Understanding it means you can build accurate diagrams quickly, debug rendering errors, and contribute to the growing ecosystem of tools that support Mermaid syntax. Developers, technical writers, and architects use it daily in documentation repos, wikis, and even live dashboards.

What Exactly Is the Mermaid Diagram Language Specification?

The specification is the formal documentation that describes how Mermaid's text-based syntax works. It covers diagram types (flowcharts, sequence diagrams, Gantt charts, class diagrams, and more), the keywords each type accepts, how nodes and connections are defined, and how styling and theming apply.

Think of it like a programming language's grammar. Just as JavaScript has rules for declaring variables and functions, Mermaid has rules for declaring diagram elements. The specification is maintained as part of the Mermaid open-source project on GitHub, and it evolves as new diagram types and features are added.

For a broader look at how different diagram syntaxes compare, see our diagram syntax reference guide for software engineers.

Which Diagram Types Does the Specification Cover?

The Mermaid specification supports a growing list of diagram types. Here are the most widely used:

  • Flowcharts for processes, decision trees, and system workflows
  • Sequence diagrams for interactions between actors or services over time
  • Class diagrams for object-oriented design and data models
  • State diagrams for representing finite state machines
  • Entity-relationship diagrams for database schema design
  • Gantt charts for project timelines
  • Pie charts for proportional data visualization
  • Git graphs for visualizing branch and commit history
  • Mindmaps for hierarchical brainstorming structures
  • Quadrant charts for priority or positioning analysis

Each diagram type has its own section in the specification with defined keywords, syntax rules, and rendering behavior. Sequence diagrams are especially popular in API documentation our sequence diagram code cheat sheet breaks down their syntax in detail.

Why Would Someone Read the Specification Instead of Just Using Examples?

Copied examples get you started, but they break down fast when you need something slightly different. The specification answers questions like:

  • What happens when two nodes have the same ID?
  • Can I nest subgraphs inside subgraphs?
  • How does Mermaid handle special characters in node labels?
  • What are the valid directions for a flowchart (TD, LR, RL, BT)?
  • How do you add links, tooltips, or click events to nodes?

Without the specification, you're guessing. With it, you know exactly what the renderer expects, which saves time and prevents diagrams from silently breaking in production documentation.

How Does the Flowchart Syntax Work in Practice?

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

You declare the diagram type with the graph keyword, set a direction (TD for top-down, LR for left-to-right), and then define nodes and connections using text characters as operators:

  • [text] rectangular node
  • (text) rounded (stadium) node
  • {text} diamond (decision) node
  • [[text]] subroutine node
  • >text] asymmetric (flag) node
  • -->| arrow with label
  • --- link without arrow
  • -.- dotted link

A simple example defining a login flow with a decision branch renders as a complete diagram when processed by any Mermaid-compatible renderer GitHub Markdown, VS Code extensions, Notion, or the Mermaid Live Editor.

What Are the Most Common Mistakes People Make with Mermaid Syntax?

Even experienced developers hit these regularly:

  1. Using reserved keywords as node IDs. Words like end, subgraph, and click are part of the syntax. Using them as node identifiers causes parsing errors.
  2. Forgetting the diagram type declaration. Every Mermaid diagram must start with a type keyword (graph, sequenceDiagram, classDiagram, etc.). Without it, nothing renders.
  3. Mismatched brackets. A missing closing bracket or parenthesis silently breaks the diagram or produces confusing output.
  4. Inconsistent indentation in subgraphs. Mermaid doesn't enforce indentation strictly, but mixing styles makes diagrams hard to maintain.
  5. Special characters in labels without escaping. Parentheses, quotes, and angle brackets inside labels can confuse the parser. Wrap complex labels in double quotes to be safe.
  6. Assuming all renderers support all features. GitHub's Mermaid renderer may lag behind the latest release. Check compatibility if something works in the live editor but not in your docs.

How Is the Specification Maintained and Versioned?

The Mermaid project follows semantic versioning. New diagram types and syntax additions land in minor or major releases. The specification lives alongside the source code, and contributors propose changes through pull requests on GitHub.

As of Mermaid v11, the project has over 70,000 GitHub stars and is used by major documentation platforms including GitHub, GitLab, Notion, and Confluence. The specification is tested against a suite of rendering snapshots to catch regressions.

If you're integrating Mermaid into your own toolchain, pin your version and test diagrams against the specific release you're targeting. Syntax behavior can shift between versions, especially for newer diagram types.

Can You Customize Diagrams Beyond the Default Specification?

Yes. The specification includes support for:

  • Themes built-in themes include default, dark, forest, and neutral. You can also define custom themes with CSS variables.
  • Styling directives apply inline styles to nodes and links using the style keyword and classDef for reusable class-based styling.
  • Click events and links attach URLs or JavaScript callbacks to nodes using the click directive.
  • Configuration set global rendering options like security level, font family, and max text size through the Mermaid initialization config.

These features are documented in the specification but often overlooked. If your diagrams look plain or you want interactivity, they're worth exploring.

When Should You Use Mermaid Over Other Diagram Tools?

Mermaid works best when diagrams need to live alongside code in Markdown files, README docs, wikis, or CI-generated reports. It's a strong fit when:

  • Your team uses Git for documentation and you want diagrams in version control.
  • You need diagrams that update when the source text changes, without re-exporting images.
  • You want non-designers to create and edit diagrams without learning a visual tool.
  • You're embedding diagrams in developer portals, static sites, or blog posts.

Mermaid is less ideal for highly visual, presentation-heavy diagrams where pixel-level layout control matters. Tools like draw.io, Lucidchart, or Figma serve that purpose better.

Quick Checklist Before Submitting a Mermaid Diagram

Use this checklist to catch common issues before your diagram goes live:

  1. Every diagram starts with a valid type declaration (graph TD, sequenceDiagram, etc.).
  2. Node IDs are unique and don't collide with reserved keywords.
  3. All brackets and parentheses are balanced.
  4. Labels with special characters are wrapped in double quotes.
  5. Subgraph names are descriptive and don't conflict with each other.
  6. The diagram renders correctly in your target platform (GitHub, GitLab, docs site).
  7. Theme and styling directives are tested against both light and dark modes if applicable.
  8. Long diagrams are broken into smaller, focused sections for readability.

For a deeper reference on syntax patterns across multiple diagram types, bookmark the full Mermaid diagram language specification guide we maintain for quick lookups.