Turning Text into Diagrams: An Introduction to Mermaid Flowcharts

If you’ve ever tried to document a process, you know the pain: wrestling with drag-and-drop shapes, lining up arrows, nudging boxes pixel by pixel… and then someone changes the process and you have to redo half the diagram.

Mermaid takes a different approach. Instead of drawing, you write your diagrams using a simple markup language. Think “Markdown, but for flowcharts.” You describe the steps and relationships in text, and Mermaid renders that description as a diagram in your browser or documentation.

Because it’s text, your diagrams can live right alongside your code, tickets, or documentation. You can version them, review them, and update them with a quick edit—not a dragging marathon.

In this article we’ll:

• Explain what Mermaid is and where it fits.
• Focus specifically on flowcharts, the most common use.
• Walk through a practical “getting started” tutorial.
• Show several examples with both Mermaid source and rendered diagrams.

What is Mermaid?

Mermaid is a text-based diagramming tool designed to be used in technical documentation, wikis, code repos, blogs, and static websites.

At a high level:

• You write a diagram in a code block, for example:
  
  flowchart TD Start --> Step1 Step1 --> End

  1 2 3 4

  flowchart TD   Start --> Step1   Step1 --> End

• A Mermaid renderer (often a JavaScript library on a web page, or your documentation platform’s built-in support) converts that text into an SVG diagram.

Mermaid supports several diagram types—flowcharts, sequence diagrams, Gantt charts, ER diagrams, and more—but flowcharts are usually where people start.

Why people like it:

• Source-controlled diagrams – The diagram is just text, so it lives in Git, gets code-reviewed, and can be diffed.
• Fast iteration – Changing a step or adding a branch is a one-line edit.
• Consistent style – Mermaid handles layout, fonts, and arrows, so your diagrams all look like they belong together.
• Embeds anywhere – Works in many tools (GitHub, GitLab, MkDocs, Docusaurus, Obsidian, etc.) and can be rendered in HTML pages or embedded in your blog or CMS.

Flowcharts in Mermaid: The Basics

Let’s start with the core concepts for flowcharts. The syntax is surprisingly small.

1. Declaring a flowchart

The first line tells Mermaid what type of diagram and what direction the flow should go:

Common directions:

• TD – Top to Down (most typical)
• LR – Left to Right
• BT – Bottom to Top
• RL – Right to Left

So a left-to-right flowchart would begin with:

2. Nodes (the boxes)

Each shape in the diagram is a node. A node has an ID and a label, and the label is wrapped in special brackets to choose the shape:

• Rectangle: id[Label]
• Rounded rectangle: id(Label)
• Stadium (pill): id([Label])
• Subroutine shape: id[[Label]]
• Circle: id((Label))
• Rhombus (decision): id{Label}

Example:

Here, start, check, approve, reject, and end are the node IDs (used to connect things). The text in brackets is what you see in the diagram.

3. Edges (the arrows)

Arrows connect nodes with a simple syntax:

That says: draw a line with an arrow from A to B.

You can also add labels to the arrow using |label|:

For flowcharts, you’ll often see a decision node with two outgoing edges labeled “Yes / No” or similar.

Example 1: Basic Yes/No Decision

Let’s turn that basic decision into something you can drop directly into your docs or a runbook.

Mermaid source

Rendered example

Getting Started: Your First Mermaid Flowchart

Now let’s go from zero to a working flowchart. We’ll look at two common scenarios:

1. You want to embed Mermaid in a simple HTML page.
2. You want to use Mermaid inside Markdown-based documentation.

Option 1: Mermaid in a standalone HTML page

If you have access to a basic web page (or can create one locally), you can load Mermaid via a <script> tag and render diagrams in the browser.

A minimal example:

How this works:

• We import Mermaid from a CDN.
• mermaid.initialize({ startOnLoad: true }) tells it to scan the page for elements with class mermaid.
• The <div class="mermaid"> contains the flowchart definition.

You can tweak:

• Theme (light/dark): mermaid.initialize({ startOnLoad: true, theme: "dark" });
• Font, spacing, etc. via Mermaid configuration or CSS, if you want more control.

Option 2: The same flowchart in Markdown docs

Here’s the same “user visits site / login” flowchart expressed as Mermaid, which you can use in Markdown-based docs or tools that support Mermaid directly.

Mermaid source

Rendered example

Drop the Mermaid source into any environment that supports Mermaid blocks and it will be rendered as a diagram; the rendered example above shows what it should look like.

A Practical Example: Support Ticket Workflow

Let’s build something more realistic: a flowchart for a basic support ticket process.

Goal: Show what happens when a new ticket arrives:

1. Ticket is created.
2. We check if enough information is provided.
3. If not, we ask the customer for more info.
4. Otherwise, we triage for priority.
5. High priority goes straight to the on-call engineer.
6. Normal priority goes into the general queue.
7. Once resolved, we close the ticket.

Mermaid source

Rendered example

This is the kind of diagram that pairs nicely with a “How we handle support tickets” knowledge base article.

Grouping Steps with Subgraphs

Once your diagrams get bigger, grouping related steps helps keep things readable. Mermaid lets you do that with subgraph.

Mermaid source

Rendered example

The subgraph blocks give you clear visual boundaries between phases like “Intake” and “Processing.”

Helpful Extras: Reuse and Comments

Once you’re comfortable with the basics, a few small features make Mermaid flowcharts even more powerful.

Reusing node definitions

You can define nodes once and refer to them from multiple places. For example:

This keeps your diagram text clean and avoids repeating labels.

Comments in diagrams

You can comment Mermaid code using %%:

Comments won’t affect the rendered chart but are helpful for collaborators reading the markup directly.

When Mermaid is a Good Fit (and When It Isn’t)

Mermaid shines when:

• You already live in text: code repos, wikis, docs.
• You want diagrams that are versionable and reviewable.
• You expect diagrams to change often (processes, architectures, workflows).

Traditional diagramming tools might still be better when:

• You need pixel-perfect marketing diagrams or brand-heavy visuals.
• Non-technical users are uncomfortable editing text and will never see the underlying markup.
• You need highly custom shapes or hand-drawn style illustrations.

In many engineering and operations contexts, though, Mermaid hits a sweet spot: fast to write, easy to maintain, and good-looking enough f