Why Mermaid Wins the Text-to-Diagram Standard in the AI Era — and What Mermaid Can Actually Do

[#1]

Ask any modern AI assistant for a diagram — "draw me the checkout flow" — and almost every one answers back in the same language: Mermaid. Not a PNG. Not a proprietary format. Plain text that renders into a diagram.

That's not a coincidence, and it matters for how you document things in Confluence. So this article answers two questions:

1. Why has Mermaid become the de facto text-to-diagram standard in the AI era — and why should you care?
2. What can Mermaid actually do? — with rendered examples and copy-paste-ready code for the eight diagrams teams use every day, plus three brand-new types from Mermaid 11.16.

I'm Simon from NGPILOT, and I build a Mermaid app for Confluence and Jira — so I'll show the diagrams inside the editor I work on. But every code block below is standard Mermaid syntax that runs anywhere Mermaid 11.16+ does. The goal is for you to walk away knowing why Mermaid is worth adopting, and exactly which diagram to reach for in each situation.

I wrote earlier about why we built yet another Mermaid app for Confluence and Jira; this is the practical follow-up.

---

Part 1 — Why Mermaid Wins the Text-to-Diagram Standard

There are dozens of diagramming tools. So why did the entire AI ecosystem quietly standardise on Mermaid? Five reasons, and together they explain the "why."

1. It's text — and AI's native output is Markdown

Large language models predict text, and their default output format is Markdown. When you ask an AI "diagram our deploy pipeline," it doesn't return a file — it returns Markdown with a ```mermaid code fence inside it. Mermaid is that fence's content: text that streams token-by-token in real time. It cannot do that with a binary image, an Excalidraw scene file, or a Visio .vsdx.

This is the deepest reason Mermaid won: the format aligns with how AI actually produces output. Mermaid lives inside Markdown, Markdown is what AI emits, and the two compose perfectly. The practical upshot is that you can paste an AI's entire Markdown response — prose, headings, code, and diagrams in ```mermaid fences — into one editor and have it all render. (If that's the workflow you want, we built Enhanced Markdown for Confluence precisely for it — full Mermaid v11 inside Markdown fences, with LaTeX and syntax-highlighted code alongside. I wrote about the Markdown-and-Mermaid workflow in detail in an earlier App Central post, "Enhanced Markdown for Confluence: Mermaid, LaTeX, and Code — All Rendered, All Inside Atlassian.")

2. It's diffable and version-controllable

A diagram stored as an image is a black box. When someone changes one arrow, your git diff shows "binary file changed" — no idea what moved. A Mermaid diagram lives in your page source (or repo) as text, so:

• Every change is a readable diff
• You can review diagram edits in a pull request
• You can resolve merge conflicts on a diagram the same way you do on code
• Blame works — you can see who changed which arrow and when

For teams that treat documentation like code, this alone is decisive.

3. It's declarative — you describe intent, not pixels

With a drag-and-drop tool, you spend your time nudging boxes into alignment. With Mermaid, you describe the structure (A connects to B, B connects to C) and the engine handles layout. This means:

• The same source reflows cleanly when you add a node — no manual repositioning
• You can generate it programmatically (from a database schema, an OpenAPI spec, a folder structure)
• It's accessible — the source is readable by screen readers and search, not trapped in pixels

4. It's portable and ubiquitous

Mermaid renders natively in GitHub, GitLab, Notion, Obsidian, VS Code, Slack, and — with the right app — Confluence and Jira. Write it once and it works everywhere. Your diagramming knowledge is transferable, not locked to one vendor's file format.

5. It keeps growing — and AI keeps up

Mermaid now ships new diagram types every release. Because each new type is just more text syntax, AI models pick them up quickly. That brings us to Part 2.

6. How Mermaid compares to the other text-to-diagram tools

Mermaid isn't the only text-to-diagram format — so why did it become the AI default? Each alternative has real strengths, but each also has a structural reason it didn't win the AI mainstream:

Graphviz (DOT) — the granddaddy of them all, dating to 1991. Excellent at graph layout (automatic node placement for dense networks, dependency graphs, org charts). Its limitation for AI: the DOT syntax is more verbose and less human-memorable than Mermaid, and it's laser-focused on graphs — there's no Gantt, no sequence, no pie. It's the right tool when you have many nodes and need a layout engine to sort them out; for everyday docs it's heavier than most teams want.

D2 — a newer, modern declarative language (from Terrastruct). Arguably the nicest syntax to read and write of the bunch, with great defaults and theming. Its constraint: a smaller ecosystem and a shorter track record, so fewer places render it natively and AI models have less training data on it. Beautiful, but not (yet) ubiquitous.

PlantUML — mature and deep for software-diagram types (sequence, class, component, deployment). Its catch: syntax that leans on pseudo-code (@startuml/@enduml, :, ;) and historically needed Java to render. Powerful for UML-heavy work, less friendly for a quick "draw me a flowchart."

Excalidraw — a different category entirely: hand-drawn, freehand diagrams and whiteboards. It's brilliant for brainstorming, sketches, and that "back of a napkin" look. But it's visual-first, not text-first — the source is a scene graph, not something you'd type or that an AI streams. It complements Mermaid rather than competing with it.

So the landscape is: Graphviz for dense auto-laid-out graphs, D2 for elegant modern syntax, PlantUML for deep UML, Excalidraw for freehand whiteboarding — and Mermaid for the broad, readable, AI-friendly middle that covers most of what teams actually document. That breadth-plus-readability is precisely why models default to it.

---

The takeaway

It's not that the other formats are worse — they each do something Mermaid can't. It's that Mermaid sits in the sweet spot: readable enough for humans, simple enough for AI, broad enough for 29 diagram types, and rendered in enough places that "diagram as text" just works. The rest of this article shows what that breadth actually looks like.

Part 2 — What Can Mermaid Actually Do?

Mermaid supports 29 diagram types. They split into two groups that are worth knowing about, because it affects how you write them and how stable the syntax is.

18 stable diagrams — syntax is locked, no -beta keyword needed. These are the workhorses; the ones you'll reach for almost every day. We'll go deep on the eight most common below, with a rendered example and copy-paste code for each.

Type	One-liner
Flowchart	Decision flows and branching logic
Sequence	Messages between systems over time
State	Object lifecycles and transitions
Class	Object-oriented structure
Entity Relationship	Data models (tables, keys, relations)
User Journey	A persona's experience across stages
Gantt	Schedules with dependencies
Pie Chart	Proportions of a whole
Git Graph	Branches and merges in a repo
Mindmap	Ideas branching from a centre
Timeline	An ordered chronology of events
Quadrant Chart	A 2×2 priority/scoring matrix
Requirement	System requirements & traceability
C4 Diagram	Software architecture (Context/Container/Component)
Kanban	A board of tickets by column
Treemap	Nested proportional rectangles
Ishikawa	Cause-and-effect (fishbone)
ZenUML	Sequence-style diagrams with declarative syntax

11 beta diagrams — Mermaid ships them behind a -beta keyword (e.g. swimlane-beta). They render reliably today, but the syntax may be refined in a future minor version, so don't pin automation to every detail. These extend text-to-diagram into newer territory. We'll look at three of the newest in Part 3.

Type	Keyword	One-liner
Swimlane	swimlane-beta	Cross-team process with one lane per actor
Architecture	architecture-beta	System/component architecture
Block	block-beta	Block-and-arrow structural diagrams
Packet	packet-beta	Network packet / bit-field layouts
Radar	radar-beta	Multi-axis comparison radar
Railroad	railroad-ebnf-beta	Grammar / syntax diagrams
Cynefin	cynefin-beta	Problem-domain sense-making framework
Sankey	sankey-beta	Flow quantities through a system
Treeview	treeView-beta	Hierarchical tree
Venn	venn-beta	Set overlaps
XY Chart	xychart-beta	Bar and line charts

Now, let's go deep on the eight stable diagrams teams use most.

---

1. Flowchart — the decision diagram

The scenario: You're documenting a bug triage process so every new engineer follows the same path. An issue comes in → is it reproducible? → what severity? → where does it go? Branching logic is exactly what a flowchart is built for, and it's the diagram AI generates most reliably.

The code:

flowchart TD
    A[New issue reported] --> B{Reproducible?}
    B -->|No| C[Request more info]
    C --> A
    B -->|Yes| D{Severity?}
    D -->|Critical| E[Hotfix branch]
    D -->|Major| F[Next sprint]
    D -->|Minor| G[Backlog]
    E --> H[Deploy & verify]
    H --> I[Close issue]
    F --> I
    G --> J[Triage review]
    J --> I

What it renders to:

Syntax notes:

• flowchart TD — TD = top-down (also LR, BT, RL).
• id[Label] = rectangle; id{Label} = decision diamond; id(Label) = rounded/stadium; id((Label)) = circle.
• A -->|Yes| B labels the arrow. Use --- for a plain line, ==> for a thick arrow.

Other scenarios: onboarding steps, "what happens when a customer cancels," CI/CD pipeline gates, escalation paths.

---

2. Sequence Diagram — who-talks-to-whom, in order

The scenario: You're onboarding engineers to how SSO login actually works — the back-and-forth between the user's browser, Confluence, and the identity provider. This is a temporal conversation: the order of messages is the whole point, and a flowchart can't capture it.

The code:

sequenceDiagram
    actor User
    participant Browser
    participant Confluence
    participant IdP as SSO Provider
    User->>Browser: Click "Sign in"
    Browser->>Confluence: GET /login
    Confluence-->>Browser: Redirect to IdP (SAML)
    Browser->>IdP: Auth request
    User->>IdP: Enter credentials
    IdP-->>Browser: SAML assertion
    Browser->>Confluence: POST assertion
    Confluence-->>Browser: Session cookie + dashboard

What it renders to:

Syntax notes:

• participant X declares a column; participant X as Display Name renames it.
• ->> = solid arrow (request); -->> = dashed arrow (response/return).
• actor User renders as a stick figure. Wrap blocks in loop ... end, alt ... else ... end, or opt ... end for loops and conditionals.

Other scenarios: OAuth flows, payment processing, API request/response contracts, microservice choreography, support ticket lifecycle.

---

3. Gantt — schedules and dependencies

The scenario: It's planning day and you need a Q3 roadmap that shows which tasks depend on which, and when they land. A table of dates doesn't communicate overlap or critical path — a Gantt does, instantly.

The code:

gantt
    title Q3 2026 Platform Roadmap
    dateFormat YYYY-MM-DD
    axisFormat %b %d
    section Foundation
        Auth refactor        :a1, 2026-07-01, 21d
        Database migration   :a2, after a1, 14d
    section Features
        New editor           :b1, 2026-07-15, 28d
        Dark mode            :b2, after a1, 14d
    section Launch
        Beta testing         :c1, after b1, 14d
        GA release           :milestone, c2, after c1, 0d

What it renders to:

Syntax notes:

• dateFormat defines how you write dates; axisFormat how the axis shows them.
• task name :id, start, duration — or :id, after otherId, duration to chain dependencies.
• section Group visually clusters tasks. :milestone, id, date, 0d renders a diamond milestone.

Other scenarios: release plans, migration timelines, marketing campaigns, hiring plans.

---

4. Entity Relationship (ER) — data models

The scenario: You're writing the data model doc for a Confluence-like knowledge base — Spaces contain Pages, Pages have Comments and Attachments, Users author everything. New engineers need to see the shape of the data before they touch the schema.

The code:

erDiagram
    SPACE ||--o{ PAGE : contains
    PAGE ||--o{ COMMENT : has
    PAGE ||--o{ ATTACHMENT : includes
    PAGE }o--|| USER : authored_by
    USER ||--o{ COMMENT : writes
    PAGE {
        string id
        string title
        string body
    }
    USER {
        string id
        string name
        string email
    }
    COMMENT {
        string id
        string body
        date created
    }

What it renders to:

Syntax notes:

• The relationship notation is the key: ||--o{. The left part (||, o|, }o) is one side's cardinality; -- is the link; the right part (o{, ||, }o) is the other side's.
  • || = exactly one; o| = zero or one; }o = zero or many; }| = one or many.
• So PAGE ||--o{ COMMENT : has reads: "one PAGE has zero-or-many COMMENTs."
• The { ... } blocks document each entity's columns — type then name, one per line.

Other scenarios: database schemas, API resource models, domain-driven design aggregates.

---

5. Mindmap — branching ideas

The scenario: You're kicking off a product launch and want a single page that shows every workstream at a glance — Engineering, Marketing, Sales, Support — each with their sub-tasks. A mindmap radiates from one centre, which mirrors how planning actually feels.

The code:

mindmap
  root((Product Launch))
    Engineering
      Feature freeze
      Bug bash
      Perf testing
    Marketing
      Landing page
      Email campaign
      Press kit
    Sales
      Demo prep
      Pricing tiers
      Enablement deck
    Support
      Runbooks
      On-call rota

What it renders to:

Syntax notes:

• Indentation is the structure — each level of indent is a child node. No arrows.
• root((Label)) = the central node (double parens = circle). Plain Label = a box.
• Keep it 2–3 levels deep; beyond that it becomes unreadable and you want a tree diagram instead.

Other scenarios: meeting agendas, OKR breakdowns, feature scope brainstorming, onboarding topic maps.

---

6. Pie Chart — proportions

The scenario: Sprint review time. You want to show how this sprint's capacity was spent — 45% features, 30% bugs, 15% tech debt, 10% docs. Simple proportions, nothing more.

The code:

pie title Sprint Issue Distribution
    "Features" : 45
    "Bugs" : 30
    "Tech debt" : 15
    "Documentation" : 10

What it renders to:

Syntax notes:

• "Label" : value — values are relative weights, not percentages. Mermaid computes the slices.
• Add a title with pie title ... on the first line.

Other scenarios: budget allocation, support ticket categories, time-tracking breakdowns, survey results.

---

7. Timeline — chronology of milestones

The scenario: A launch roadmap that's less granular than a Gantt — just the major beats across quarters: beta, public beta, GA, iterate. Timeline is the right tool when you care about sequence and milestones, not task durations and dependencies.

The code:

timeline
    title Product Launch Roadmap
    section Q3 2026
        Beta release   : Internal testing only
        Public beta    : Open sign-ups
    section Q4 2026
        GA launch      : Full release
        Post-launch    : Iterate on feedback

What it renders to:

Syntax notes:

• section Period groups events; each Event : detail line sits under it.
• Unlike Gantt, there are no dates or durations — just ordered events. That's the feature, not a limitation: it reads as a story.

Other scenarios: company history, incident postmortem chronologies, project retrospectives, changelog highlights.

---

8. Git Graph — branches and merges

The scenario: You're documenting your team's GitFlow branching strategy so new hires stop committing straight to main. The whole value is visualising where branches fork and merge.

The code:

gitGraph
    commit
    branch develop
    checkout develop
    commit
    branch feature/auth
    checkout feature/auth
    commit
    commit
    checkout develop
    merge feature/auth
    checkout main
    merge develop
    commit type: HIGHLIGHT tag: "v1.0"

What it renders to:

Syntax notes:

• commit adds a commit on the current branch; branch name forks; checkout name switches; merge name brings a branch back in.
• commit type: HIGHLIGHT tag: "v1.0" marks a release commit with a tag.

Other scenarios: release management docs, explaining trunk-based vs GitFlow, onboarding to a repo's conventions.

---

Part 3 — The Beta Group: Where Mermaid Is Headed Next

The 18 stable diagrams above cover most day-to-day needs. Mermaid's 11 beta diagrams are where the project is actively growing — they extend text-to-diagram into territory the workhorses can't reach. All 11 render reliably today; the -beta keyword just signals that syntax may still be refined in a future minor version.

Here's the full beta group, then a closer look at the three newest (added in Mermaid 11.16).

Type	Keyword	What it's for
Swimlane	swimlane-beta	Cross-team process with one lane per actor
Cynefin	cynefin-beta	Problem-domain sense-making (Clear/Complicated/Complex/Chaotic/Confusion)
Railroad	railroad-ebnf-beta	Grammar / syntax diagrams for languages & formats
Architecture	architecture-beta	System and component architecture
Block	block-beta	Block-and-arrow structural diagrams
Packet	packet-beta	Network packet / bit-field layouts
Radar	radar-beta	Multi-axis comparison (e.g. skill assessments)
Sankey	sankey-beta	Flow quantities through a system (budget, traffic)
Treemap	treemap	Nested proportional rectangles (org/asset breakdowns)
Treeview	treeView-beta	Hierarchical tree (file structures, org charts)
Venn	venn-beta	Set overlaps
XY Chart	xychart-beta	Bar and line charts

The three newest (Mermaid 11.16)

Swimlane — who does what in a cross-team process. A flowchart shows what happens; a swimlane shows who does it. Each subgraph becomes a lane; write all edges after all lanes so hand-offs render cleanly.

swimlane-beta LR
  subgraph Customer
    order[Place order]
    receive[Receive delivery]
  end
  subgraph Sales
    review[Review order]
    confirm[Confirm and invoice]
  end
  subgraph Warehouse
    pick[Pick items]
    pack[Pack shipment]
  end
  subgraph Shipping
    dispatch[Dispatch]
  end
  order --> review
  review --> pick
  pick --> pack
  pack --> dispatch
  dispatch --> confirm
  confirm --> receive

Cynefin — what kind of problem is this? Dave Snowden's framework helps a team ask "what kind of situation are we in?" before acting. Two people arguing about a solution are often actually disagreeing about which of the five domains the problem sits in — this diagram makes that visible. The five domain names are fixed keywords; the --> transitions show how situations drift between domains.

cynefin-beta
  complex
    "Probe - run safe-to-fail experiments"
    "Sense emerging patterns"
  complicated
    "Sense - gather data"
    "Analyze - apply expert knowledge"
  clear
    "Sense - categorize"
    "Respond - apply best practice"
  chaotic
    "Act - stabilize first"
    "Sense - what is happening"
  confusion
    "Break the problem down"
  clear --> chaotic : "Complacency"
  chaotic --> complex : "Stabilized"
  complex --> complicated : "Pattern identified"
  complicated --> clear : "Best practice codified"

Railroad — documenting grammars and file formats. Syntax diagrams visualise the valid structure of a language, config schema, or DSL — scannable in a way raw EBNF text never is. Each line is one rule (name = definition ;); "text" = literal terminal, | = choice, * = repeat, + = one-or-more. Use it for documenting query languages, upload-file formats, or any DSL your product defines.

railroad-ebnf-beta
title "Arithmetic Expression Grammar"

expression = term ( ( "+" | "-" ) term )* ;
term       = factor ( ( "*" | "/" ) factor )* ;
factor     = number | "(" expression ")" ;
number     = digit+ ;
digit      = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ;

The other eight betas round out specialised cases: Sankey for budget/traffic flows, Radar for multi-axis scoring, Packet for network bit-fields, Architecture and Block for structural views, Treeview for hierarchies, Venn for set overlap, and XY Chart when you need an actual bar or line chart rather than a relational diagram.

---

Putting AI + Mermaid into a Confluence page

Here's the workflow the "AI era" actually enables, end to end:

1. Describe your diagram to an AI assistant in plain language ("draw a sequence diagram for our SSO login").
2. Paste the Mermaid it returns into a Mermaid editor.
3. Preview live, tweak the text, save.

No image editing, no re-drawing when a box changes. The diagram is text from start to finish — which is exactly why it composes so well with AI.

The Mermaid+ editor has all 29 types as one-click Quick Templates in the middle column, with a live preview on the left and a code editor on the right. There's also a built-in syntax guide (the ? button) listing every type with hover-to-insert examples — because, honestly, I keep forgetting the syntax too.

The diagrams above were rendered with Mermaid 11.16, the same version the app runs. A pre-rendered SVG is cached when you save, so readers never wait on a diagram engine on page load, and colours adapt to dark mode without re-rendering. (I covered why that caching matters in the previous article.)

---

Quick reference — which diagram for which job?

Stable (syntax locked, your daily drivers):

You want to show…	Use
Branching decision logic	Flowchart
Messages between systems over time	Sequence
A project schedule with dependencies	Gantt
A data model (tables & relationships)	ER
Ideas branching from one concept	Mindmap
Proportions of a whole	Pie
An ordered chronology of milestones	Timeline
Branches and merges in a repo	Git Graph
A 2×2 priority/scoring matrix	Quadrant Chart
Object lifecycles and transitions	State
Software architecture (C4)	C4 Diagram
Cause-and-effect (fishbone)	Ishikawa

Beta (-beta keyword, syntax may refine):

You want to show…	Use
A process and who owns each step	Swimlane
What kind of problem a team faces	Cynefin
The valid structure of a language/format	Railroad
Flow quantities through a system	Sankey
Nested proportional breakdowns	Treemap
Multi-axis comparison / scoring	Radar
Hierarchical tree (file structures, orgs)	Treeview
Set overlaps	Venn

---

Over to you

The throughline is simple: Mermaid won the text-to-diagram standard because it's text, and text is what AI, version control, and search all understand natively. The 18 stable diagrams cover the vast majority of what teams document day to day — and the 11 beta diagrams show that "text-to-diagram" now reaches into strategy, cross-team processes, language specs, and quantitative charts.

Picking the right tool for the job

At NGPILOT we build for the whole text-to-diagram spectrum, because — as the comparison above showed — no single format is best for everything. A quick guide:

• The AI-to-page workflow → paste an AI's full Markdown response (prose + ```mermaid fences + code) into one editor that renders all of it. That's the native shape of how AI outputs diagrams.
  • Enhanced Markdown for Confluence — full Mermaid v11 inside Markdown, with LaTeX and syntax-highlighted code.
• Most docs, most of the time → Mermaid as a standalone diagram. Start here.
  • Mermaid+ for Confluence (free for teams up to 10 users)
  • Mermaid+ Diagrams for Jira
• Dense graphs / auto-layout (dependency graphs, large networks) → Graphviz, where the DOT engine shines.
  • Graphviz Charts for Confluence
• Freehand sketches, whiteboards, brainstorming → Excalidraw, when you want the "back of a napkin" look rather than a structured diagram.
  • Excalidraw+ for Confluence
  • Excalidraw Diagrams + Whiteboards for Jira

All of them run on Atlassian Forge — nothing leaves your site — and each has a live-preview editor so you see the diagram as you write the source.

But the question I'd really love to hear answered: what's the diagram you currently struggle to make — and have you tried just asking an AI for it in Mermaid? Drop it in the comments; I read every one, and a few diagram types in the app today exist because someone described a problem in a thread exactly like this.

— Simon from NGPILOT