Mermaid Diagrams in Markdown: Text-Based Visualization for Developers

You’ve been there. Someone asks you to document a system architecture, a deployment pipeline, or an API flow. You fire up a drawing tool, spend 45 minutes dragging boxes around, export a PNG, and drop it into your repo. Two weeks later the architecture changes, and that PNG is already wrong. Nobody updates it. Nobody ever updates it.

Mermaid fixes this by letting you write diagrams as text, right inside your Markdown files. The diagram lives next to your code, gets versioned with Git, and renders automatically on platforms like GitHub, GitLab, and Obsidian. No image exports. No separate tools. Just text that turns into visuals.

What Mermaid actually is

Mermaid is a JavaScript library that takes a text-based description and renders it as an SVG diagram. You write something like this inside a fenced code block:

```mermaid
flowchart LR
    A[User] --> B[Server]
    B --> C[(Database)]
```

And it turns into a clean left-to-right flowchart with three connected nodes. The syntax is compact, readable, and version-controllable.

Mermaid supports several diagram types out of the box:

Flowcharts for processes, algorithms, and architecture overviews
Sequence diagrams for API calls, auth flows, and service-to-service interactions
Gantt charts for project timelines, sprint plans, and release schedules
Class diagrams, ER diagrams, state diagrams, and more

This article series focuses on the three most practical types for day-to-day engineering work: flowcharts, sequence diagrams, and Gantt charts.

Where you can use it

One of the best things about Mermaid is how widely supported it is. You don’t need to install anything special in most cases.

Platform	Support
GitHub (README, Issues, PRs)	Built-in rendering
GitLab	Built-in rendering
Obsidian	Native support
Notion	Via code blocks
VS Code / Cursor	Extension: “Markdown Preview Mermaid Support”
Docusaurus	Built-in
Confluence	Via plugin
Jupyter Notebooks	Via extension

You can also use the Mermaid Live Editor to prototype diagrams in your browser and export them as SVG or PNG.

Syntax fundamentals

Before jumping into specific diagram types, there are a few universal rules worth knowing.

Node IDs must not contain spaces. Use camelCase or PascalCase:

UserService --> DatabaseHandler

Labels with special characters go in double quotes:

A["Process #1 (main)"] --> B["Step: validation"]

Avoid reserved words as node IDs. Words like end, subgraph, graph, and flowchart will break your diagram. Use something like processEnd or endNode instead.

Don’t hardcode colors. If you add style directives with explicit hex colors, your diagram will look fine in light mode and terrible in dark mode (or vice versa). Let the renderer’s theme handle it.

Themes are available if you want a different look. Add this at the top of your diagram:

%%{init: {'theme': 'forest'}}%%

Available themes: default, forest, dark, neutral, base.

Comments use %% and won’t render:

%% This note is only visible in the source code

A taste of each diagram type

Here’s a quick preview of each type so you know what to expect in the rest of this series.

Flowcharts

Flowcharts describe processes and decision trees. They’re the most versatile diagram type in Mermaid.

```mermaid
flowchart TD
    Start([Start]) --> Input[Get user input]
    Input --> Check{Valid?}
    Check -->|Yes| Process[Process data]
    Check -->|No| Error[Show error]
    Process --> Done([End])
    Error --> Input
```

Key shapes: rectangles [text] for actions, diamonds {text} for decisions, rounded ([text]) for start/end points.

Directions: TD (top-down), LR (left-right), BT (bottom-up), RL (right-left).

Arrow types: --> solid arrow, -.-> dashed, ==> thick, -->|label| with text.

Sequence diagrams

Sequence diagrams show how different actors or services communicate over time. They’re perfect for documenting API interactions, login flows, or microservice choreography.

```mermaid
sequenceDiagram
    participant User
    participant API
    participant DB

    User->>API: GET /api/products
    API->>DB: SELECT * FROM products
    DB-->>API: Result set
    API-->>User: 200 OK (JSON)
```

Solid arrows (->>) represent requests. Dashed arrows (-->>) represent responses. Participants appear in the order you declare them.

Gantt charts

Gantt charts show tasks across a timeline with durations and dependencies. Useful for sprint planning, project roadmaps, and release tracking.

```mermaid
gantt
    title Landing Page Redesign
    dateFormat YYYY-MM-DD

    section Design
    Competitor analysis    :a1, 2026-03-10, 3d
    Create mockups         :a2, after a1, 5d
    Design approval        :a3, after a2, 2d

    section Development
    Frontend build         :a4, after a3, 7d
    Testing                :a5, after a4, 3d

    section Launch
    Deploy                 :a6, after a5, 1d
```

Tasks can depend on each other using after taskId. Sections group related work visually.

Why text-based diagrams matter

If you’ve worked on a team where architecture docs go stale within a sprint, you already get why this matters. But here are the specific wins:

Version control. Diagrams live in the same repo as your code. When someone refactors a service, the diagram diff shows up in the same PR.
Review-friendly. Text diffs are easy to review. “You added a new service to the sequence diagram” is visible in a code review, unlike a replaced PNG where you’d need to eyeball two images.
No tool lock-in. You don’t need Lucidchart, Draw.io, or Figma licenses. Any text editor works.
Low friction. Writing A --> B is faster than dragging a connector between two boxes. The gap gets wider as diagrams grow.
Searchable. Text is grep-able. You can search your codebase for “Database” and find every diagram that references it.

The tradeoff is that you give up pixel-level control over positioning. Mermaid decides where nodes go, and sometimes the layout isn’t perfect. For most engineering documentation, that’s an acceptable exchange.

What’s next

This is part 1 of a three-part series. The next two articles go deeper:

Part 2: Flowcharts and Sequence Diagrams covers everything from simple linear flows to nested subgraphs, CI/CD pipelines, OAuth 2.0 sequences, and microservice interactions with parallel processing.
Part 3: Gantt Charts and Advanced Tips walks through project planning diagrams with critical paths, milestones, task statuses, and the practical tips that make Mermaid work well in real projects.

If you want to experiment right now, try the interactive playground below or open the Mermaid Live Editor.

Interactive playground

Edit the code and switch between tabs to see the result. Pick any diagram type to get started.

Try it:

TL;DR

What Mermaid does:

Renders diagrams from plain text inside Markdown
Supported natively on GitHub, GitLab, Obsidian, Docusaurus, and more

Three main diagram types:

Flowcharts for processes and architecture
Sequence diagrams for service interactions over time
Gantt charts for project timelines

Why it matters:

Diagrams live in your repo, version-controlled and reviewable alongside code