# Mermaid

> Diagrams written as short lines of text. The tool draws the picture for you.

**Field:** Design  
**Category:** Design Tools  
**Also known as:** Mermaid.js, Mermaid Diagram, Mermaid Diagrams

## Think of it like

It is like telling a friend who sits next to whom. They draw the seat map for you.

## Definition

Mermaid is a way to make diagrams by writing short lines of text. You type a line like A --> B, and Mermaid draws box A with an arrow to box B. It can draw flowcharts, sequence diagrams, Gantt charts, class diagrams and many more. GitHub, GitLab and many note apps draw Mermaid inside Markdown files. Because the diagram is text, a change shows up in a code review like any other line.

## Example

Emma adds a Mermaid flowchart to her project's README on GitHub. When the login steps change, she edits two lines of text, and the picture redraws.

## Example code

```mermaid
flowchart LR
    A[Sign in] --> B{Password right?}
    B -- Yes --> C[Home page]
    B -- No --> A
```

Four lines of text. Mermaid turns them into a sign-in flowchart with a loop back.

## Why it matters

The diagram lives beside the code and changes with it. Nobody needs a drawing tool to fix it.

## Common mistake

Fighting the layout. Mermaid places the boxes itself, so a diagram that needs exact places is easier in a drawing tool.

## Three principles

- **Text to picture.** Write lines, get a diagram.
- **Lives in Markdown.** GitHub and GitLab draw it in Markdown.
- **Auto layout.** You pick the links, it picks the places.

## Related terms

- [Diagramming Software](https://learn.benibix.com/term/design/diagramming-software)
- [draw.io](https://learn.benibix.com/term/design/drawio)
- [Markdown](https://learn.benibix.com/term/development/markdown)
- [Unified Modeling Language (UML)](https://learn.benibix.com/term/development/uml)
- [README File](https://learn.benibix.com/term/development/readme)

## Told apart from

- [Mermaid vs draw.io](https://learn.benibix.com/compare/mermaid-vs-drawio): People think Mermaid and draw.io are two apps for the same job, and they are not. In draw.io you drag every box into place by hand. In Mermaid you write lines of text, and it places the boxes for you. A Mermaid diagram lives in a Markdown file beside the code, so it gets reviewed and fixed like code. draw.io wins when the exact layout matters.
- [PlantUML vs Mermaid](https://learn.benibix.com/compare/plantuml-vs-mermaid): People think PlantUML and Mermaid are the same tool with two names, and they are not. Both turn text into diagrams. Mermaid runs in the browser, and GitHub draws it right inside Markdown. PlantUML runs on Java and covers more of UML, but GitHub will not draw it for you. Pick Mermaid for a README, and PlantUML for strict UML.

## Taught in

- [Diagramming Software](https://learn.benibix.com/learn/design-design-tools/diagramming-software): Design Tools, 12/12

![Three panels, each making the same two boxes, Shop above Pay, joined by an arrow. Sketch by hand, like Excalidraw: wobbly hand-drawn boxes and a curved arrow, marked rough on purpose. Drag shapes, like draw.io: a strip of shapes on the left and two neat boxes joined by a straight line, marked move a box and the line follows. Write text, like Mermaid: two lines of code, flowchart TB and A Shop arrow B Pay, with an arrow down to the two boxes it draws.](https://learn.benibix.com/diagrams/des-diagram-tools.svg)

---

Source: https://learn.benibix.com/term/design/mermaid
Author: Behnia Zarei (a developer in Vienna, Austria, who builds and teaches data, AI and business intelligence at BENIBIX)
Publisher: BENIBIX Learn (https://learn.benibix.com/)
Last updated: 2026-11-19
Licence: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). Quote freely with attribution.
