Diagram (Mermaid)

A diagram draws a flowchart, a sequence of messages, a timeline or another kind of chart from a few lines of text, using a popular free tool called Mermaid. You write what is connected to what, and the drawing follows.

Changing a diagram is as easy as editing a sentence: no boxes to drag, and no picture to make again in another program. The text lives in the page, so the next person can change it too.

Insert it

Type the command and press Enter, or choose + on the toolbar, then Diagram (Mermaid). You get a small example flowchart to change. If text is selected, the diagram takes its place.

A diagram is a code block whose language is Mermaid diagram, so you can also make one from any Code block by choosing Mermaid diagram in its language menu, or by typing ```mermaid at the start of a line and pressing Enter.

To change the text, choose Source at the top right of the diagram; choose Diagram to see the drawing again.

Kinds of diagram, and when to use each

The first word of the text says what kind of diagram it is. Here are the most useful kinds, each drawn live from its text. Choose Source on any of them to see how it is written, and copy it as a start for your own.

Flowchart

flowchart TD
  A[Expense to claim] --> B{More than 500?}
  B -->|No| C[Submit it in the expenses app]
  B -->|Yes| D[Ask your manager to approve it]
  D --> C
  C --> E[Paid with your next salary]

Steps and choices: a process, an approval path, what to do when something breaks. flowchart TD draws it top to bottom; flowchart LR, left to right.

Sequence diagram

sequenceDiagram
  participant C as Customer
  participant S as Shop
  participant P as Payment provider
  C->>S: Place order
  S->>P: Charge card
  P-->>S: Payment approved
  S-->>C: Confirmation email

Who sends what to whom, in order: how two systems talk to each other, or the hand-offs between teams.

State diagram

stateDiagram-v2
  state "In review" as Review
  [*] --> Draft
  Draft --> Review: Submit
  Review --> Draft: Changes requested
  Review --> Approved: Approve
  Approved --> [*]

The stages something moves through, and what moves it on: a document’s review, an order, a support request.

Gantt chart

gantt
  title Office move
  dateFormat YYYY-MM-DD
  section Planning
  Choose furniture :a1, 2026-10-01, 10d
  Order furniture :a2, after a1, 5d
  section Moving
  Pack :b1, 2026-10-26, 5d
  Move day :milestone, m1, 2026-11-02, 0d

A plan over time, with each task a bar on a calendar and what has to wait for what.

Timeline

timeline
  title Kestrel Sync releases
  2024 : Version 1
  2025 : Shared folders
       : Faster first sync
  2026 : Version 2, with offline editing

Events in order, such as a project’s history or a product’s releases, without the detail of a Gantt chart.

Pie chart

pie title Support requests by topic
  "Signing in" : 42
  "Billing" : 28
  "Exports" : 18
  "Other" : 12

Shares of a whole, for a quick impression. When readers need the exact numbers, a table with a Chart drawn from it serves them better.

Mind map

mindmap
  root((Launch))
    Marketing
      Blog post
      Newsletter
    Support
      Help pages
      Training
    Sales
      Price list

Ideas branching out from one topic: a brainstorm, or the parts of a project at a glance. Indentation sets what belongs to what.

User journey

journey
  title A new starter’s first week
  section First day
    Collect laptop: 3: New starter, IT
    Meet the team: 5: New starter
  section Rest of the week
    Set up accounts: 2: New starter, IT
    First project: 4: New starter

How an experience feels, step by step, each step scored from 1 (bad) to 5 (good) and with the people involved: onboarding, a customer’s first order.

Quadrant chart

quadrantChart
  title Ideas by effort and impact
  x-axis Low effort --> High effort
  y-axis Low impact --> High impact
  quadrant-1 Plan carefully
  quadrant-2 Do first
  quadrant-3 Maybe later
  quadrant-4 Skip
  Dark theme: [0.3, 0.8]
  Offline mode: [0.8, 0.9]
  New icons: [0.2, 0.25]
  Custom fonts: [0.75, 0.2]

Things placed on two scales at once, such as ideas by effort and impact, to decide what to do first.

Entity relationship diagram

erDiagram
  CUSTOMER ||--o{ ORDER : places
  ORDER ||--|{ ORDER_LINE : contains
  PRODUCT ||--o{ ORDER_LINE : "appears in"

How the tables in a database relate to each other: which one holds many of which. For developers and data teams.

Class diagram

classDiagram
  class Customer {
    name
    email
    placeOrder()
  }
  class Order {
    date
    total()
  }
  Customer "1" --> "*" Order : places

The parts of a program and how they connect, with what each one holds and does. For developers.

Git graph

gitGraph
  commit
  branch feature
  checkout feature
  commit
  commit
  checkout main
  merge feature
  commit

Branches and merges in a code repository, to explain how a team works with Git.

And more

The Mermaid in this version of Tesria also draws XY charts, Sankey diagrams, Kanban boards, block diagrams, packet diagrams, requirement diagrams and C4 architecture diagrams, among others. Mermaid’s own documentation, at mermaid.js.org, shows how to write every kind.

Changing and removing a diagram

• Source and Diagram, at the top right, switch between the text and the drawing. While you edit, change the text in Source, then choose Diagram to check the result. Readers can open Source too, to see how it is made.

• Copy copies the text.

• The language menu, at the left while you edit: choose another language and the diagram becomes an ordinary code block showing its text.

A mistake in the text shows Mermaid’s own message where the drawing would be, usually naming the line that went wrong. Diagrams are drawn in light or dark colors to match the theme Tesria is in.

Good practice

• Start from an example and change one line at a time, checking with Diagram as you go.

• Keep it small. Ten or fifteen boxes are about as many as a reader can follow; split a bigger diagram into several.

• Label the arrows when the reason for a step is not obvious, as the Yes and No of the flowchart above.

• Say in a sentence what the diagram shows. Not every reader can see it, and the sentence helps those who can.

Related elements

• Code block shows text as code rather than drawing it.

• Chart draws the numbers in a table as bars, lines or a pie.

• Image for a picture made in another program.