Mermaid Diagrams for Developers: Examples, Syntax, and a Free Live Editor

Mermaid is a text-based diagram language that turns a few lines of Markdown-friendly syntax into flowcharts, sequence diagrams, entity-relationship models, class diagrams, state machines, Gantt charts, and more. If you have ever pasted a mermaid code fence into a GitHub README and watched it render on the pull request page, you already know the appeal: diagrams that live next to the code, version control cleanly, and do not require opening Visio or Figma for a simple architecture sketch.

This guide is a practical tour of Mermaid diagrams for software teams - what they are good for, the syntax patterns you will use most often, copy-paste examples, and how to edit them in a free online Mermaid live editor when you want instant preview and export without installing anything.

If you want to try examples as you read, open the free Mermaid live editor in another tab. Every diagram on this page also has an Edit control that loads the same source into that tool.

Why Mermaid diagrams stick in engineering workflows#

Teams keep adopting Mermaid for a few durable reasons:

1. Diff-friendly. A flowchart is a text change in a pull request, not a binary asset nobody can review.
2. Works where docs already live. GitHub, GitLab, many static site generators, and documentation platforms render Mermaid natively or with a small plugin.
3. Fast to draft. You can sketch a request path or schema relationship while writing the design doc, without context-switching into a drawing tool.
4. Portable. The source is plain text. Share a gist, a README section, or a URL that encodes the diagram.

The tradeoff is familiar to anyone who has written YAML: the syntax is simple until it is not. A free Mermaid diagram editor with live preview closes that gap - you type, see the result, fix a typo, export SVG or PNG when you need a slide or a wiki page.

Mermaid flowchart example (architecture and decision trees)#

Flowcharts are the default diagram type for system overviews, onboarding maps, and branchy decision logic. Start with a direction (TD top-down, LR left-right), then connect nodes with arrows.

flowchart LR
  Client[Client] --> Edge[API gateway]
  Edge --> Auth{Authenticated?}
  Auth -->|No| Login[Login service]
  Auth -->|Yes| App[App service]
  App --> Cache[(Cache)]
  App --> DB[(Database)]
  Login --> Auth

Syntax notes

• flowchart LR sets layout left-to-right (TD / TB for top-down).
• Node shapes: [rectangle], (rounded), {diamond}, [(cylinder)] for datastores.
• Edge labels use A -->|label| B.
• Subgraphs group related services when the chart gets crowded.

Flowcharts are the right Mermaid diagram when you need “how does a request move through the system?” more than “which tables reference which.”

Mermaid sequence diagram example (APIs and auth)#

Sequence diagrams show time-ordered messages between participants. They are ideal for login flows, webhooks, and multi-service handshakes.

sequenceDiagram
  participant User
  participant Web as Web app
  participant API
  participant Auth
  participant DB as Database
  User->>Web: Submit credentials
  Web->>API: POST /session
  API->>Auth: Validate
  Auth->>DB: Lookup user
  DB-->>Auth: User row
  Auth-->>API: OK + claims
  API-->>Web: Set session cookie
  Web-->>User: Redirect to dashboard

Syntax notes

• participant renames actors (Auth as Identity service).
• Solid arrows ->> are requests; dashed -->> are responses.
• Note over A,B: text and alt / opt / loop blocks cover branches without drawing spaghetti.

When the question is “who calls whom, and in what order?”, start with a Mermaid sequence diagram instead of a flowchart.

Mermaid ER diagram example (data models)#

Entity-relationship diagrams document tables, keys, and relationships. They pair well with migration reviews and onboarding for backend teams.

erDiagram
  WORKSPACE ||--o{ REPOSITORY : contains
  REPOSITORY ||--o{ DOCUMENT : has
  USER ||--o{ WORKSPACE : owns
  USER {
    uuid id PK
    string email UK
    string name
  }
  WORKSPACE {
    uuid id PK
    uuid owner_id FK
    string plan
  }
  REPOSITORY {
    uuid id PK
    uuid workspace_id FK
    string full_name UK
  }
  DOCUMENT {
    uuid id PK
    uuid repository_id FK
    string slug
    string title
  }

Syntax notes

• Relationships: ||--o{ (one-to-many), ||--|| (one-to-one), }o--o{ (many-to-many).
• Column lines use a simple type token, then name, then optional PK / FK / UK.
• Keep names alphanumeric; Mermaid is pickier than SQL about special characters.

If you already have CREATE TABLE SQL and do not want to hand-write Mermaid ER syntax, the free SQL to ER diagram generator converts common Postgres, MySQL, and SQLite table definitions into a Mermaid erDiagram with live preview and SVG export.

Mermaid class diagram example (modules and domain types)#

Class diagrams show types, fields, methods, and dependencies. Use them for domain models and for explaining how packages talk to each other without dumping a full dependency graph.

classDiagram
  class DocIndexer {
    +string repoId
    +index()
    +search(query)
  }
  class DocumentStore {
    +save(doc)
    +get(id)
  }
  class McpServer {
    +listTools()
    +callTool(name, args)
  }
  DocIndexer --> DocumentStore : writes
  McpServer --> DocumentStore : reads
  McpServer --> DocIndexer : triggers

Syntax notes

• class Name { ... } holds members; + public, - private is common convention.
• Relationships: --> association, <|-- inheritance, *-- composition.
• Keep the chart small. A full monorepo class dump is unreadable; document the slice the reader needs.

Mermaid state diagram example (lifecycle and status machines)#

State diagrams clarify allowed transitions: job status, subscription lifecycle, PR review states.

stateDiagram-v2
  [*] --> Queued
  Queued --> Running: worker claims job
  Running --> Succeeded: finish ok
  Running --> Failed: error
  Failed --> Queued: retry
  Succeeded --> [*]
  Failed --> [*]: give up

Use state diagrams when illegal transitions are expensive (billing, indexing, deployments) and prose alone leaves “can we go from Failed back to Running?” ambiguous.

Gantt and planning charts#

Mermaid Gantt charts are lightweight release timelines - fine for a design doc, not a replacement for a project tool.

gantt
  title Docs automation rollout
  dateFormat YYYY-MM-DD
  section Foundation
  Connect GitHub          :a1, 2026-07-01, 3d
  First index             :a2, after a1, 2d
  section Team rollout
  MCP setup for agents    :b1, after a2, 4d
  Friday Cleanup trial    :b2, after b1, 7d

Putting Mermaid diagrams in GitHub and Markdown docs#

A Mermaid fence in Markdown looks like this:

```mermaid
flowchart TD
  A[Start] --> B[Done]
```

GitHub renders those fences in README files, issues, and pull request descriptions. Many static doc sites (Docusaurus, MkDocs with a plugin, VitePress plugins, and others) do the same.

Practical tips

• Prefer smaller diagrams. A PR that adds a 200-line chart is hard to review.
• Name nodes for the reader, not for the implementation file path.
• When a diagram changes with the code, put it next to the module it describes - or accept that it will drift.
• For slides and Confluence, export SVG or PNG from a Mermaid live editor so you are not screenshotting a half-zoomed browser tab.

Free Mermaid live editor: preview, share, export#

Hand-writing Mermaid in a text area without feedback is how most people learn the hard way that a missing arrow or quote breaks the chart. A dedicated Mermaid diagram editor should:

• Render live as you type - no save-and-reload loop.
• Stay private for day-to-day sketching (diagrams in the browser, not uploaded by default).
• Share via URL so a teammate sees the exact same source.
• Export SVG and PNG for docs, tickets, and decks.
• Ship examples for flowchart, sequence, ER, class, mindmap, and Gantt so you are never starting from a blank page.

That is what the free Moxie Docs Mermaid live editor is built for:

Open it when you are learning Mermaid syntax, reviewing a diagram before pasting it into a README, or exporting a chart for a design review. No signup for the free tool path.

Mermaid vs drawing tools (and when to use each)#

Mermaid wins when the diagram is part of the engineering record. Drawing tools win when the artifact is primarily visual collaboration.

Keeping diagrams true as the codebase changes#

A Mermaid flowchart in a README is only as good as last week’s understanding of the system. The failure mode is familiar: the service was split, the auth path changed, and the diagram still shows the old boxes.

That is a documentation problem, not a Mermaid syntax problem.

Moxie Docs connects to GitHub, indexes the repository, and keeps generated architecture docs and diagrams aligned with source over time - with reviewable Cleanup PRs rather than silent overwrites. Use the free Mermaid editor to draft and export quickly; connect a repo when you want those diagrams and the surrounding docs to stay current on every merge.

Quick Mermaid cheatsheet#

Try it now#

1. Open the free Mermaid diagram editor.
2. Load a flowchart or sequence example, or paste one of the fences from this article.
3. Tweak labels until the diagram matches your system.
4. Copy the Mermaid source into a README, or export SVG/PNG for a design review.
5. When you need ER diagrams from real CREATE TABLE SQL, use the SQL to ER diagram generator.

Mermaid diagrams work because they treat architecture as text: reviewable, searchable, and close to the code. A live editor removes the friction of learning the syntax. Living docs remove the friction of keeping the pictures honest after the next merge.