Create your first diagram

Mermaid diagrams start as text and render as visuals. You write the structure — nodes, connections, labels — and Mermaid handles the layout automatically.

This guide walks through creating a diagram from scratch in the editor. If you’d rather describe what you want and let AI generate the syntax, start with Generate a diagram with AI →.

Before you start

You’ll need a Mermaid account. Sign up free →

On the Basic plan? You can create up to 3 diagrams with limited AI. It’s enough to get started — if you hit the limit, upgrading to Plus gives you unlimited diagrams and 300 AI credits per year.

Choose how to start

There are four ways into a new diagram:

• Write or paste syntax if you have code ready or are comfortable writing Mermaid syntax from scratch. Paste in existing code and it renders immediately, or start from a blank editor and build from there.
• Start from a template if you’re new to Mermaid and want a working diagram to edit rather than starting from nothing. Templates cover every diagram type — load one, replace the content with your own.
• Vibe diagramming if you’d rather describe what you want in plain language and let AI generate the syntax for you. Type a prompt, get a diagram. Refine it conversationally from there. Covered in full in Generate a diagram with AI →.
• Voice diagramming (beta) if you want to speak your diagram into existence. Describe your diagram out loud and Mermaid transcribes and renders it in real time. Useful when you’re thinking out loud or want to sketch something quickly without touching a keyboard.

Create a diagram

1. Go to your dashboard.
2. Click New diagram.
3. Select a diagram type. If you’re not sure which to use:

The editor opens with a sample diagram loaded for that type.

The editor

The editor has two panels. Write in the left panel and the diagram renders live in the right panel as you type. A few things worth knowing before you start:

• Autosync keeps the rendered diagram in step with your code as you type. If you’re working on a large diagram and performance slows down, turn autosync off under More options and render manually when you’re ready.
• Local timeline saves your work automatically after every change. If you make an edit you want to undo beyond what Cmd+Z covers, open the local timeline from the left panel and step back to an earlier version.
• Pan & zoom lets you navigate large rendered diagrams without losing your place. Enable it under More options, then use your trackpad or scroll wheel to move around.
• Highlight sync keeps your code and your diagram in step as you edit. Click a node in the rendered diagram and the corresponding line highlights in the editor. Edit the code and the node lights up. When you’re deep in a complex flowchart, this is the thing that keeps you from losing your place. Available for flowcharts and sequence diagrams.
• Diagram documentation opens the full syntax reference for the diagram type you’re working on in a new tab — useful when you know what you want to do but need to look up the exact syntax.

Write your first flowchart

Every diagram starts with a type declaration. For a flowchart, that’s flowchart followed by the direction:

A simple content approval workflow:

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

This renders as a left-to-right flow with two decision points and a loop back to drafting on rejection.

Nodes

Nodes are the building blocks of a flowchart. Their shape signals meaning.

Node IDs and labels are separate. The ID (A) is used to reference the node in connections. The label (Label) is what renders in the diagram. If you reference a node multiple times, define the label once and use the ID everywhere else:

flowchart LR
    A[Start] --> B[Review]
    B --> C[Done]
    B --> A

Connections

Connections define how nodes relate. The type of connection carries meaning.

Add labels to connections to describe the path:

B -->|Approved| C
B -->|Rejected| A

Subgraphs

Group related nodes into a labeled section using subgraph:

flowchart LR
    subgraph Review
        B[Send to reviewer] --> C{Approved?}
    end
    A[Draft] --> Review
    C -->|Yes| D[Publish]
    C -->|No| A

Subgraphs are useful for showing stages in a process, grouping by team or system, or separating a subprocess from the main flow.

Load a template

If you want a working example to edit rather than starting from scratch:

1. Click the book icon in the top right.
2. Select a diagram type.
3. The template loads into the editor — edit from there.

Templates are available for all our diagrams, from flowcharts to timelines to Sankey diagrams. Explore the full library for the complete set.

Common questions

• The diagram isn’t rendering. There’s a syntax error in the code. Mermaid highlights the line causing the issue. Check for mismatched brackets, missing arrows, or incorrect node references. You can also click Mermaid AI in the left panel and ask it to repair the diagram — it identifies and fixes syntax errors directly.

• The layout looks off. Try changing the direction. LR (left to right) works well for processes. TD (top down) works better for hierarchies. The same diagram can read very differently depending on direction.

• A node label has special characters. Wrap the label in quotes: A["This label has (parentheses)"]. This applies to commas, semicolons, and other characters that Mermaid might try to parse.

• The word “end” is breaking my diagram. Capitalize it: End or END. Lowercase end is a reserved word in Mermaid’s parser.

What’s next?

• Describe what you want and let AI write the syntax | Generate a diagram with AI →
• Apply a theme or define custom colors | Apply a theme →
• Export as PNG or SVG, or send a live link | Share your diagram →
• Use the Visual Editor →