Mermaid.js Complete Guide: Diagrams from Text
Mermaid turns plain text into diagrams. Write a few lines of readable syntax and get a flowchart, sequence diagram, or gantt chart - no dragging boxes.
Mermaid is a tool that generates diagrams from text. Instead of dragging shapes around a canvas, you write a few lines in a simple, readable syntax, and Mermaid renders the corresponding diagram. It is open source, runs in the browser, and has become the de facto standard for diagram-as-code because it is supported natively in GitHub, GitLab, Notion, VS Code, and countless other tools. If you have ever seen a diagram rendered directly inside a Markdown file or a GitHub README, there is a good chance Mermaid drew it.
The appeal is straightforward once you experience it. A text-based diagram lives alongside your code, versions cleanly in Git, is trivial to edit, and never suffers the drift where documentation and the diagram fall out of sync. You describe the structure and let the tool handle layout, which for many diagrams is faster than positioning everything by hand. This guide introduces Mermaid end to end: the diagram types it supports, the basic syntax, how rendering works, and how to get productive quickly. You can write and preview Mermaid live in the editor at /diagram-tools/mermaid-editor while you read.
How Mermaid syntax works
Every Mermaid diagram begins with a keyword that declares its type. You write `flowchart TD` for a top-down flowchart, `sequenceDiagram` for a sequence diagram, `classDiagram` for a class diagram, `gantt` for a gantt chart, and so on. That first line tells Mermaid which grammar to expect for everything that follows, and each diagram type has its own concise syntax tuned to what it describes.
Within a flowchart, you define nodes and connect them with arrows. A line like `A --> B` creates two nodes, A and B, with an arrow from one to the other. You add labels with brackets: `A[Start] --> B[Process]` gives the nodes readable text. Different bracket shapes produce different node shapes - square brackets for rectangles, curly braces for decision diamonds, parentheses for rounded boxes. The whole philosophy is that the text reads almost like a description of the diagram, so someone can understand the source without rendering it.
The diagram types Mermaid supports
Mermaid is not just for flowcharts - it supports a broad range of diagram types, each with dedicated syntax. Knowing what is available helps you reach for the right one. Here are the main types you will use.
- Flowcharts (`flowchart` or `graph`): nodes and arrows for processes and logic, the most-used type.
- Sequence diagrams (`sequenceDiagram`): interactions between participants over time, drawn with lifelines and messages.
- Class diagrams (`classDiagram`): classes, attributes, methods, and relationships for object-oriented design.
- Entity-relationship diagrams (`erDiagram`): database tables and the relationships between them.
- State diagrams (`stateDiagram-v2`): states and the transitions between them for state machines.
- Gantt charts (`gantt`): project timelines with tasks, durations, and dependencies.
- Pie charts, user journeys, git graphs, mindmaps, timelines, and more - the type list keeps growing with each release.
Your first Mermaid diagram
Let us build a simple flowchart. Start with the type declaration `flowchart TD` (TD means top-down). On the next lines, define the flow: `A[Start] --> B{Is it valid?}` creates a start node and a decision. Then branch from the decision with labelled arrows: `B -->|Yes| C[Process it]` and `B -->|No| D[Reject]`. The text between the pipes becomes the arrow label. Put those lines together and Mermaid renders a complete little flowchart with a decision and two labelled branches.
Notice how much you did not have to do. You never specified where any node sits, how big it is, or how the arrows route - Mermaid's layout engine handled all of it. You described the logical structure, and the tool produced a clean visual. For diagrams where the exact positioning does not matter, this is enormously faster than manual placement, and when you change the structure, the layout re-flows automatically instead of requiring you to rearrange boxes by hand.
The direction keyword after the type controls layout: `TD` or `TB` for top-to-bottom, `LR` for left-to-right, `RL` and `BT` for the reverse directions. Switching a diagram from vertical to horizontal is a one-word change, which would be a tedious manual rearrangement in a drag-and-drop tool.
Where Mermaid fits and its limits
Mermaid shines when diagrams live near code and change often: architecture docs in a repo, sequence diagrams in a design document, ER diagrams next to a schema. Because the source is text, it diffs cleanly in pull requests, so a diagram change is reviewable like any code change. It is also excellent for diagrams you generate programmatically, since producing Mermaid text from data is trivial.
Its limits are the flip side of its strengths. You give up precise control over layout - the auto-layout is good but you cannot nudge a single node exactly where you want it the way you can in a visual editor. Highly designed, pixel-perfect diagrams for presentations are usually better made in a drag-and-drop tool. The sweet spot is technical diagrams where clarity and maintainability matter more than exact visual polish. A tool like Atlas Diagram Studio bridges both worlds: you can write Mermaid in the editor at /diagram-tools/mermaid-editor, then switch to visual editing on the canvas at /diagrams for fine-tuning, getting the speed of text and the control of direct manipulation.