Write diagram syntax

Mermaid syntax is plain text with a defined structure. Once you understand the basics, you can build and edit any diagram without touching the AI panel — and you’ll know exactly what to change when a diagram needs updating.

This guide covers flowchart syntax in depth. For other diagram types, the same principles apply; the OSS docs have full syntax references for every type. Browse the OSS syntax docs →

How syntax works

Every diagram starts with a type declaration that tells Mermaid what kind of diagram to render:

flowchart LR
sequenceDiagram
erDiagram
mindmap
gantt

Everything that follows defines the content — nodes, connections, labels, styles, and groupings. The diagram renders in real time as you type in the editor.

Flowchart direction

For flowcharts, the direction comes right after the type declaration:

Direction	Code	When to use
Left to right	LR	Processes, workflows, timelines
Top to bottom	TD or TB	Hierarchies, org charts, decision trees
Bottom to top	BT	Reverse hierarchies
Right to left	RL	Less common — specific layout needs

Direction has a bigger impact on readability than most people expect. The same diagram can be clear or cluttered depending on which way it flows. If a layout looks off, try changing the direction before adjusting anything else.

Nodes

Nodes are the building blocks of a flowchart. Shape carries meaning — use it deliberately.

Syntax	Shape	When to use
A[Label]	Rectangle	Default — steps, actions, tasks
A(Label)	Rounded rectangle	Softer steps, start and end points
A{Label}	Diamond	Decisions with branching paths
A((Label))	Circle	Events, endpoints, loop connectors
A[/Label/]	Parallelogram	Input or output
A[(Label)]	Cylinder	Databases, data stores
A[[Label]]	Subroutine	Subprocess or referenced flow
A>Label]	Asymmetric	Flags, tags

Node IDs and labels are separate. The ID is used to reference the node in connections — the label is what renders in the diagram. Define the label once and use the ID everywhere else:

flowchart LR A[Content brief] --> B[Draft] B --> C{Ready for review?} C -->|Yes| D[Send to reviewer] C -->|No| B D --> E[Published]

Tip: Don't use the word end in all lowercase as a node ID or label — it's a reserved word and breaks the parser. Use End, END, or a different word entirely.

Connections

Connection type carries meaning. Use the right one for what you’re showing.

Syntax	Renders as	When to use
—>	Arrow	Default directional flow
---	Line	Relationship without direction
-.->	Dotted arrow	Optional, async, or conditional path
==>	Thick arrow	Primary or critical path
—o	Circle end	Aggregation or “zero or many” relationship
—x	Cross end	Termination or blocking step
<—>	Bidirectional arrow	Two-way relationship

Tip: If a connection label starts with the letter o or x, add a space before it or capitalize it. -->|ok| renders as a circle edge — use -->| ok| or -->|Ok| instead.

Subgraphs

Group related nodes into a labeled section using subgraph. Useful for showing stages in a process, grouping by system or team, or isolating a subprocess from the main flow.

flowchart LR subgraph Intake A[Request received] --> B{Complete?} B -->|No| C[Request more info] end subgraph Review D[Assign reviewer] --> E{Approved?} E -->|Yes| F[Publish] E -->|No| G[Return to author] end B -->|Yes| D

Subgraphs can be connected to nodes outside them using the subgraph ID. You can also set direction inside a subgraph independently from the parent diagram.

Code snippets

The snippets panel in the editor has pre-written blocks for common patterns — a useful shortcut when you know the shape you want but not the exact syntax. Click Code snippets in the left panel to browse them, then click any snippet to drop it into the editor.

Use the diagram documentation panel

While editing, click Diagram documentation in the left panel to open the full syntax reference for the diagram type you’re working on in a new tab — without losing your place in the editor. Useful when you’re working with a less familiar diagram type or need to look up a specific property.

Common questions

The diagram isn’t rendering. There’s a syntax error somewhere. Mermaid highlights the line causing the issue — check for mismatched brackets, missing arrows, or node IDs that don’t match. You can also open the Mermaid AI panel and click Fix with AI to let it identify and repair the issue automatically.
Labels with special characters aren’t rendering correctly. Wrap the label in quotes: A["Label with (parentheses) and, commas"]. This applies to commas, semicolons, and any character Mermaid might try to parse as syntax.
My subgraph connections aren’t working. Make sure you’re referencing the correct node IDs, not the subgraph label. Nodes inside a subgraph are still referenced by their own IDs.
The word “end” is breaking my diagram. Capitalize it: End or END. Lowercase end is reserved.

What’s next?

Skip the syntax and describe what you want instead | Generate a diagram with AI →
Click to build instead of type | Use the Visual Editor →
Define colors, styles, and themes | Create custom styles →