Creating Mermaid Diagrams

Mermaid turns text into diagrams. Use a flowchart for steps and decisions, or a sequence diagram for messages passed between people or systems.

The examples below show the source to copy. To see them drawn, use a Mermaid-enabled Markdown viewer or the Mermaid Live Editor. Support depends on the viewer and its Mermaid version. About Mermaid.

A first flowchart

flowchart LR
    idea["Propose an idea"] --> review{"Ready to try?"}
    review -->|Yes| trial["Run a small trial"]
    review -->|No| revise["Revise the idea"]
    revise --> review

Read this as: propose an idea, make a decision, then try it or revise it. The revision returns to the decision.

idea is a node’s ID; "Propose an idea" is its displayed label. Reuse an ID when referring to the same node. Keep IDs short and labels meaningful.

Flowchart syntax at a glance

Syntax	Meaning
flowchart LR	Lay out the flow from left to right
flowchart TD	Lay out the flow from top to bottom
step["Do something"]	Rectangular step
choice{"Ready?"}	Diamond decision
finish(["Done"])	Rounded endpoint
first --> second	Arrow from one node to another
first --- second	Connection without an arrowhead
%% Explain a choice	Source comment on its own line

Write review -->|Yes| trial to label an arrow. Quote labels that contain spaces or punctuation. Mermaid flowchart reference.

Group related steps

flowchart TD
    subgraph preparation["Preparation"]
        collect["Gather ideas"] --> choose["Choose one"]
    end
    choose --> trial["Try it"]

subgraph starts a group; end closes it. The group gives readers a boundary around related work. Subgraph syntax.

Show a conversation over time

sequenceDiagram
    participant Person
    participant Toolkit
    Person->>Toolkit: Open a cheatsheet
    Toolkit-->>Person: Show the reference
    Note over Person: Read the example

Read a sequence diagram from top to bottom. participant declares a named column. Here, ->> draws a solid message arrow and -->> a dotted one; the labels explain the exchange. Mermaid sequence diagram reference.

Put Mermaid in Markdown

In a viewer that supports Mermaid, place the diagram inside a code fence labeled mermaid:

```mermaid
flowchart LR
    read["Read"] --> try["Try"]
```

In the Live Editor, paste only the diagram source inside the fence. Leave out the backtick lines. Mermaid usage guide.

When a diagram breaks

• Check the first line: diagram types use different syntax.
• Check matching brackets, braces, and quotes.
• In flowcharts, avoid lowercase end as a node ID or unquoted label; it has a special role in grouping.
• If two intended nodes become one, give them different IDs.
• If the example works in one viewer but fails in another, check the Mermaid versions they support.

Start with two nodes and one arrow, then add one relationship at a time. Keep a short explanation alongside the diagram so its meaning survives when rendering is unavailable.