Tutorial: Create Flowcharts with Mermaid Directly in Your Markdown Files

What You'll Build

In this tutorial, you'll learn how to create flowcharts using Mermaid — a text-based diagramming language that renders inside Markdown files, GitHub READMEs, GitLab docs, Notion pages, and many documentation platforms. By the end, you'll be able to write a readable flowchart from scratch in under 10 minutes.

Prerequisites: Basic familiarity with Markdown. No design skills or special tools required.

Step 1: Set Up Your Environment

Mermaid diagrams are written inside a fenced code block with the mermaid language tag. Here's how to get a live preview:

GitHub / GitLab: Mermaid is natively supported — just push a .md file and view it in the browser.
VS Code: Install the Markdown Preview Mermaid Support extension for live preview.
Mermaid Live Editor: Visit mermaid.live for an instant browser-based playground with no setup.
Obsidian: Supported natively in preview mode.

For this tutorial, open mermaid.live in your browser — it gives you instant visual feedback as you type.

Step 2: Write Your First Flowchart

A Mermaid flowchart block looks like this in Markdown:

```mermaid
flowchart TD
  A[Start] --> B[Do something]
  B --> C{Decision?}
  C -->|Yes| D[Do this]
  C -->|No| E[Do that]
  D --> F[End]
  E --> F
```

Let's break this down:

flowchart TD — declares a flowchart with top-down direction. Use LR for left-to-right.
A[Start] — a node with ID A and label "Start". Square brackets create a rectangle.
--> — an arrow connecting two nodes.
C{Decision?} — curly braces create a diamond (decision node).
|Yes| — a label on an arrow.

Step 3: Understand Node Shapes

Mermaid supports multiple node shapes, each with different bracket syntax:

Shape	Syntax	Use for
Rectangle	`A[Label]`	Process steps, actions
Rounded rectangle	`A(Label)`	Start/end terminals
Diamond	`A{Label}`	Decisions / branches
Circle	`A((Label))`	Connection points
Parallelogram	`A[/Label/]`	Input / Output
Cylinder	`A[(Label)]`	Databases

Step 4: Build a Real-World Example

Let's model a CI/CD pipeline flow:

```mermaid
flowchart LR
  A([Push to branch]) --> B[Run unit tests]
  B --> C{Tests pass?}
  C -->|Yes| D[Build Docker image]
  C -->|No| E[Notify developer]
  D --> F[Push to registry]
  F --> G{Branch = main?}
  G -->|Yes| H[Deploy to production]
  G -->|No| I[Deploy to staging]
  H --> J([Done])
  I --> J
```

This renders as a readable, left-to-right pipeline diagram. Notice how the natural reading direction (left to right) matches the flow of a pipeline — a deliberate choice using LR instead of TD.

Step 5: Add Styling (Optional)

You can apply styles to individual nodes using the style keyword:

```mermaid
flowchart TD
  A[Start] --> B[Process]
  B --> C[End]
  style A fill:#2D6BE4,color:#fff
  style C fill:#22c55e,color:#fff
```

Use color sparingly — to highlight critical paths, error states, or entry/exit points.

Best Practices for Mermaid Flowcharts

Keep node IDs short: Single letters or short abbreviations (A, DB, API). Long IDs make the source hard to read.
One direction consistently: Don't mix TD and LR in a single diagram — it creates visual confusion.
Maximum ~15 nodes per diagram: Beyond that, split into sub-diagrams or link with ref.
Label every decision branch: Always put |Yes| and |No| (or equivalent) on diamond outflows.
Commit diagrams with the code they describe: Put them in the relevant README.md or docs/ folder, not a separate wiki that gets out of date.

What's Next

Once you're comfortable with flowcharts, Mermaid supports many other diagram types using the same text-based approach: sequence diagrams (sequenceDiagram), class diagrams (classDiagram), entity-relationship diagrams (erDiagram), Gantt charts, and more. The syntax stays consistent — what you've learned here transfers directly.