Intro to Mermaid: Draw Diagrams from Text — Flowcharts, Sequence Diagrams, and Gantt
Mermaid lets you create flowcharts and sequence diagrams by writing short text instead of drawing shapes with a mouse. This article explains what Mermaid is, how text becomes a diagram, the basic syntax for flowcharts, sequence diagrams, and Gantt charts, how to write nodes and arrows, how to use it in GitHub and Notion, and the benefits of managing diagrams as code.
When you want to add a diagram to a spec or design note, you open a drawing app, line up rectangles, connect them with lines, and type in labels — have you ever lost time to that kind of busywork? Mermaid is a mechanism that lets you finish such diagramming by "just writing short text." Instead of dragging with a mouse, you describe the structure of the diagram like a sentence, and it is automatically converted into a flowchart, a sequence diagram, and more. This article explains, step by step, what Mermaid is, how text becomes a diagram, and the basic ways to write it.
What Is Mermaid
Mermaid is an open-source diagramming tool (and syntax) that automatically generates diagrams from text you write. It is implemented in JavaScript, and its biggest feature is that you can express a diagram's structure with a concise, easy-to-read-and-write syntax, much like Markdown. It covers many of the diagrams commonly used in software development and documentation, including flowcharts, sequence diagrams, Gantt charts, class diagrams, and pie charts.
With traditional drawing apps, you had to hand-adjust the position of every shape and the routing of every line. With Mermaid, you only write the relationships — "what connects to what and how" — and it arranges the placement and layout automatically. You can focus on the content of the diagram itself instead of fussing over its appearance.
The easiest way to see what syntax produces what diagram is to type code into the Mermaid Diagram Editor and watch the diagram redraw in real time. First, get a feel for how adding just one line of text adds a node to the diagram.
How Text Becomes a Diagram
A Mermaid diagram always begins with one line that declares which type of diagram it is. For example, a flowchart starts with graph TD, and a sequence diagram with sequenceDiagram. Mermaid reads this leading declaration to decide how to interpret the lines that follow.
graph TD A[Start] --> B[Process] B --> C[End]
In the example above, graph TD declares "a flowchart that flows from top to bottom," and the following lines express the relationships "draw an arrow from A to B, and from B to C." A and B are names that identify nodes (shapes), and the text inside [ ] is what is shown on that node. --> means an arrow.
The key point is that the writer never specified any coordinates. As long as you write the relationship "A connects to B," Mermaid uses a layout engine to place the shapes and tidies things up so the lines do not overlap. This is the heart of the "diagrams born from text" mechanism.
Flowchart Basics (graph TD)
The most commonly used type is the flowchart. At the start, you follow graph with the direction of the diagram. There are four basic directions.
| Keyword | Meaning |
|---|---|
| TD (or TB) | Top down |
| BT | Bottom to top |
| LR | Left to right |
| RL | Right to left |
A node's shape changes with the type of brackets that follow its name. This lets you visually distinguish "process," "decision," "start/end," and so on.
A[Text]… rectangle (a standard processing step)B(Text)… rounded rectangleC{Text}… diamond (condition / decision)D((Text))… circle
Arrows also come in varieties, and you can attach a label (description) to a line. This is handy for showing conditional branches.
graph TD A[Login screen] --> B{Auth ok?} B -->|Yes| C[Home screen] B -->|No| D[Show error]
--> is a solid arrow, and -->|label| is the way to add text to an arrow. There are also --- (a line with no arrow) and -.-> (a dotted line), among other expressions that match the nature of the relationship. Once you know just graph TD, -->, and branching with { }, you can draw practical flowcharts almost entirely.
Sequence Diagrams and Gantt Charts
Beyond flowcharts, Mermaid supports many frequently used diagrams. Here are two representative ones.
1. Sequence diagrams
A sequence diagram shows in what order participants (or systems) interact, following the flow of time. It is useful for explaining the order of API calls or the flow of a login process. You declare sequenceDiagram at the start.
sequenceDiagram User->>Server: Login request Server-->>User: Return token
Conventionally, ->> is a solid arrow (a request) and -->> is a dotted arrow (a response). The text after the colon becomes the message content. Time progresses from top to bottom, and the interactions are drawn between the vertical lines (lifelines) on the left and right.
2. Gantt charts
A Gantt chart represents the duration and schedule of tasks with horizontal bars, and is used for managing project progress. You declare gantt at the start and describe the date format, sections, and the start date and duration of each task.
gantt title Development schedule dateFormat YYYY-MM-DD section Design Requirements :a1, 2026-07-01, 5d Basic design :a2, after a1, 7d
5d means "5 days," and after a1 means "start after task a1 finishes." Because you can arrange tasks by their dependency on a previous task instead of writing dates directly, it is robust against schedule reshuffling. The shortcut to learning these syntaxes too is to paste them into the Mermaid Diagram Editor and check how the actual diagram is drawn.
Using It in GitHub and Notion
A major reason Mermaid spread so quickly is that leading documentation services support it out of the box. Just specify the language name mermaid on a Markdown code block and write the syntax inside, and it is automatically converted into a diagram when displayed.
- GitHub: Mermaid renders inside README.md, Issues, and Pull Request comments. If you write your design as text, it is conveyed as a diagram to anyone who views the repository.
- Notion: Choose Mermaid as the language of a code block to display it as a diagram. It is easy to embed diagrams in spec notes and manuals.
- Others: GitLab, Obsidian, Zenn, and various static site generators — supported services increase year by year.
In these environments, there is no need to upload a separate image file. Because the diagram itself is written in the body as text, you can update it with the same feeling as editing prose. A big advantage is that during review, what changed in the diagram is shown as a text difference (diff).
Benefits of Managing Diagrams as Code
The essential value of Mermaid is not merely that diagramming is fast. It is that you can treat a diagram as "text, that is, code." This brings properties decisively different from a diagram stored as a traditional image file.
| Mermaid (text) | Image file | |
|---|---|---|
| Ease of editing | Just rewrite the text | Reopen in a drawing app |
| Change history | Differences remain as text | Differences are hard to see |
| Version control | Easy to manage with Git | Hard to handle as binary |
| Search / reuse | Text search is possible | The contents cannot be searched |
If a diagram is text, you can version it with Git just like source code, leaving a history of "when, who, and what changed." Team review is easier, and rolling back to a past diagram is simple. You can also copy and reuse it as part of your prose, and it is easy to ask an AI to "write a flowchart of this process in Mermaid" and have it generated. Against the long-standing problem that diagrams and documents tend to drift apart, Mermaid, which lets you manage everything centrally as text, is a powerful solution.
Without overthinking it, try writing in the Mermaid Diagram Editor one line at a time from graph TD, and experience how the diagram grows. Moving your hands and visually confirming how syntax maps to the diagram is the fastest path to mastery.
Please note that this article is intended to provide general information. Mermaid's syntax and the specifications of supporting services may be updated, so make your decision after checking the latest official documentation when you actually use it.
FAQ
What is Mermaid?
Mermaid is an open-source diagramming tool (and syntax) that automatically generates diagrams from text you write. Instead of drawing shapes with a mouse, you write concise text describing "what connects to what and how," and it is converted into flowcharts, sequence diagrams, and more. Placement and layout are arranged automatically, so you can focus on the content of the diagram.
Can I use it without programming knowledge?
For basic diagrams, you need almost no programming knowledge. For a flowchart, you just write "graph TD" at the top and connect nodes with arrows like "A --> B." The syntax is concise like Markdown, so you can learn it bit by bit, much like writing prose.
What does the "TD" in graph TD mean?
TD is a keyword that specifies the diagram direction and means Top Down (from top to bottom). There are also LR (left to right), RL (right to left), and BT (bottom to top), which you choose based on your needs. For example, when you want a horizontal flow, graph LR lines up nodes from left to right.
Can I display diagrams directly in GitHub and Notion?
Yes. GitHub READMEs and Issues, and Notion code blocks, support Mermaid out of the box. Just specify "mermaid" as the language of a code block and write the syntax, and it is automatically converted into a diagram when displayed. There is no need to upload images; you can update the diagram simply by editing text.
Is the code I enter in the Mermaid Diagram Editor sent to a server?
WAZA TOOLS' Mermaid Diagram Editor runs entirely in your browser, so the code you enter is never sent to or stored on a server. It works on smartphones too, and you can create and preview diagrams as many times as you like, for free.