Mermaid.js Syntax: The Golden Rules 📜 #

A condensed guide to writing clean, effective, and error-free Mermaid.js diagrams.

✨ Core Principles #

These rules are the foundation for all Mermaid diagrams.

Declare Diagram Type First Always begin with the diagram type keyword (e.g., flowchart TD, sequenceDiagram). This is non-negotiable.
```
%% ✅ Correct
flowchart TD
    A --> B
```
Unique IDs are Essential Every node/participant/entity needs a unique identifier for linking. Simple IDs are best; avoid special characters.
```
%% ✅ Correct
flowchart LR
    userLogin["User Login"] --> authService["Auth Service"]
```
Indentation is Structure In hierarchical diagrams (mindmap, flowchart subgraphs), indentation (typically 2 spaces) defines parent-child relationships. Be consistent.
```
%% ✅ Correct
mindmap
  root((Start))
    Child 1
    Child 2
```

Handling text correctly is critical to avoid syntax errors.

Quote Any Text with Special Characters If a label, title, or description contains spaces, parentheses, brackets, or any other non-alphanumeric character, you must enclose it in double quotes ("").
```
%% ❌ Incorrect: '()' are special characters
%% flowchart LR
%%    A[Node (v1)] --> B

%% ✅ Correct
flowchart LR
    A["Node (v1)"] --> B
```
Escaping Double Quotes To use a literal double quote (") inside a quoted string, you must use its HTML entity code: ".
```
flowchart LR
    A["This is the &quot;main&quot; node"] --> B
```
Forbidden Characters in IDs Avoid using special characters in the unique IDs for nodes (the part before the brackets). Stick to alphanumeric characters and underscores for maximum compatibility (e.g., user_login is safer than user-login).

Mistake	❌ Incorrect Code	✅ Fix & Explanation
Missing Diagram Type	`A --> B`	Add the declaration. `flowchart TD; A --> B`
Spaces in IDs/Labels	`My Node --> Another Node`	Use quotes. `"My Node" --> "Another Node"` or better, `myNode["My Node"] --> anotherNode["Another Node"]`
Incorrect Arrow Syntax	`A -- > B` or `A ->>> B`	Use correct syntax. `A --> B` (default), `A --- B` (no arrow), `A -- text --> B` (with text). Check docs for diagram-specific arrows.
Mixing Diagram Features	`sequenceDiagram; A[Square Node]`	Use native syntax. Sequence diagrams use `participant`, not flowchart nodes. Stick to the syntax for the declared diagram type.
Inconsistent Indentation	`mindmap; root; Child1; Child2`	Use consistent indentation. `mindmap; root; Child1; Child2` (2 spaces is standard).

Use Meaningful IDs userLoginButton is far more descriptive and maintainable than node1 or A.
Comment Your Code Use %% to explain complex logic or sections within your diagram definition. It makes future edits much easier.
```
flowchart TD
    %% This section handles user authentication
    A[Enter Credentials] --> B{Check Auth}
```
Keep It Simple (KISS) If a diagram becomes too complex to read in its text form, it’s probably too complex for its audience. Break it down into multiple, simpler diagrams.
Use Subgraphs for Grouping Logically group related nodes in flowcharts to improve readability and structure.
```
flowchart TD
    subgraph "Authentication"
        A[User] --> B[Password]
    end
```
Consult the Official Docs When in doubt, the Mermaid.js official documentation is the ultimate source of truth. Syntax can vary slightly between diagram types.