Mermaid is an open-source JavaScript library that renders diagrams from plain text. Instead of dragging shapes around in a drawing tool, you describe the diagram in a short, readable syntax and Mermaid draws it for you — flowcharts, sequence diagrams, Gantt charts, ER diagrams and more than twenty other types.
flowchart LR
T[Text you write] --> M((Mermaid)) --> D[Diagram you share]Why diagrams as code?
Diagrams drawn by hand go stale because updating them is tedious. When a diagram is text, updating it is as easy as editing a line, and it gains all the benefits of code:
- Version control — diagrams live in Git next to the code they describe, with history and reviews.
- Consistency — Mermaid handles layout, spacing and styling, so every diagram looks clean.
- Speed — typing
A --> Bis faster than drawing and aligning two boxes and an arrow. - Portability — the same text renders on GitHub, GitLab, Notion, Obsidian, Confluence and in your own apps.
- AI-friendly — language models can read and write Mermaid, so you can generate or fix diagrams from a description.
A first Mermaid diagram
Every Mermaid diagram starts with a keyword that names the diagram type, followed by its content. Here is a complete flowchart:
flowchart TD
Start --> Idea{Good idea?}
Idea -- Yes --> Build[Build it]
Idea -- No --> StartPaste it into the MermaidViewer editor and you'll see the rendered diagram instantly. Change TD to LR and the layout flips from top-down to left-to-right.
Which diagram types does Mermaid support?
Mermaid covers software, business and data use cases. The most popular are flowcharts, sequence diagrams, class diagrams, ER diagrams, state diagrams and Gantt charts. There are also mindmaps, timelines, git graphs, pie charts, quadrant charts, sankey diagrams, XY charts, C4 diagrams and newer types like architecture, kanban, radar and treemap. See the full list on the diagram types page.
Where can you use Mermaid?
- GitHub and GitLab render ```mermaid code blocks in Markdown files, issues, pull requests and wikis.
- Notion, Obsidian, Confluence (via apps) and many docs tools support Mermaid blocks natively or through plugins.
- Docs sites built with Docusaurus, MkDocs, VitePress or Astro have Mermaid plugins.
- Online editors like MermaidViewer let you write, preview, export and share diagrams without installing anything.
How to get started
- Open the free online Mermaid editor — no sign-up needed.
- Pick a template or a sample for the diagram type you need.
- Edit the text on the left and watch the preview update live.
- Download a PNG (JPG, SVG and PDF are on Pro), copy the Markdown, or create a share link.
Stuck on syntax? Describe your diagram in plain English and let the AI diagram generator write the Mermaid code for you.
Who maintains the library
People who ask what is mermaid usually get a one-line answer and a tiny flowchart. The useful next layer is who ships the code, how a diagram file is organized, and what the renderer does with that file before you ever see a picture.
Mermaid is an open source JavaScript library. Knut Sveidqvist started it, and it is now a large project maintained in the mermaid-js GitHub organization under the MIT license. That license is why so many hosts bundle the renderer. You still live with the build the host has pinned.
A diagram that renders in the editor can fail on a site that ships an older build. The text is portable. The feature set is whatever that build implements. When you need a newer diagram type than the host has, export an image and keep the source next to it. The export guide covers PNG, SVG, and PDF.
How a diagram file is put together
Every diagram is one block of text, and the block has a shape you can learn once. The first meaningful line is a keyword. That keyword names the diagram type: flowchart, sequenceDiagram, erDiagram, gantt, mindmap, and the others on the diagram types index. The lines under the keyword are statements in that type's grammar. A second keyword in the same block is not a second picture. It is a parse error. One block, one keyword, one diagram.
Configuration can sit above the keyword. Newer files use a short YAML frontmatter block. Older files use an %%{init}%% directive on the first line. Both can set the theme before the parser reads the body. Hosts that lag sometimes ignore the YAML and still honor the directive. The themes guide shows both forms. Leave them out until the default colors are wrong for the page.
Under the keyword, most types share one habit even when the punctuation changes. You invent a short id, you attach a label a person can read, and you connect ids. In a flowchart the id comes first and the label sits in brackets: pay[Charge card]. The id is what other lines point at. The label is what the reader sees. Change the label and keep the id, and every arrow still lands on the same node. Change the id, and the arrows that used the old one miss.
Flowcharts also take a direction on the keyword line: TD, LR, BT, or RL. That token is layout, not a node. Sequence diagrams don't use it. They list participants, then messages. ER diagrams list entities and relationships. The keyword tells you which syntax page to open. Guessing the punctuation from a flowchart habit is how a sequence diagram breaks on line 2.
Comments are lines that start with %%. Mermaid strips them before parsing, so they never appear in the picture. Put a comment on its own line. A comment glued to the end of a statement is a common way to break a file that looked finished. Blank lines are safe. Indentation is decoration in a flowchart and structure in a mindmap. A mindmap copied with flowchart spacing ends up with the wrong parent, or with a parse error if the indents disagree.
Here is a file that still has the parts worth naming: a comment, a keyword with a direction, ids, labels, and links.
flowchart LR
%% Source of truth for the charge path
Cart[Cart] --> Pay[Charge card]
Pay --> Ledger[(Ledger)]
Pay --> Receipt[Receipt]Switch LR to TD in the editor and the layout moves while the meaning stays. When a label needs parentheses, quote it and keep the id one word: api["GET /v2/orders"].
From the text to an SVG
Rendering is a pipeline. Knowing the stages makes the error messages less mysterious, and it tells you which stage you can actually fix.
The host hands your text to Mermaid. Mermaid reads the keyword and selects that diagram's parser. The parser either builds an internal model or stops with a line number. "Syntax error in text" comes from this stage, before anything is drawn. The syntax error guide covers quotes, the word end, colons, dates, and mindmap indents because those are parser failures.
If the parser succeeds, a layout step assigns coordinates. For a flowchart, the long-standing layout is dagre, a graph layout library Mermaid ships with. A newer option is ELK. You opt in by starting the file with flowchart-elk instead of flowchart. ELK is calmer on some large graphs. It will not rescue a diagram that is trying to say three things at once. Sequence diagrams, ER diagrams, and Gantt charts use their own layout code. You don't switch those to dagre.
The last stage writes SVG. Nodes become shapes, labels become text, and arrows become paths. The host inserts that SVG into the page. Pan and zoom, when a host offers them, wrap the SVG. They are not a second rendering. What you see is the vector drawing.
PNG and PDF happen after this pipeline. A PNG is a snapshot of the SVG at a chosen scale. A vector PDF keeps drawing commands. The CLI runs the same pipeline in a headless browser: npx -p @mermaid-js/mermaid-cli mmdc reads a .mmd file and writes SVG or PNG. Pin the Mermaid version when CI output has to match your laptop.
flowchart LR
Text[Diagram text] --> Parser
Parser --> Model[Internal model]
Model --> Layout
Layout --> SVG[SVG]If the parser stops, layout and SVG never run. If the picture looks wrong and there is no error, the parse succeeded and the model is what you described: a missing edge, a reversed "one" and "many", or a direction that fights the content. You change a line and render again. The text stays the source. Hand-edited SVG nudges disappear on the next render. Hosts also drop click callbacks inside the SVG for security, so put real links in the surrounding Markdown, as the GitHub guide describes.
A tour of picking a type
Reciting every diagram type doesn't help you choose. Pick by the question a reader will ask, then open that type's syntax page and copy a small example into the editor.
If the question is "what happens next, and what if the answer is no", use a flowchart. Decisions are diamonds. Direction TD fits a policy with branches. Direction LR fits a pipeline. This is the right default when you are unsure, because a lot of process notes are flowcharts wearing a paragraph. The flowchart tutorial builds one from a direction through arrows. Later sections on this site go into subgraphs, chained edges, and link styles.
If the question is "who sends what, and in which order", use a sequence diagram. Participants are columns. Messages are arrows. Time runs down the page. Use this when a flowchart would hide the return trip, the retry, or two services being busy together. The sequence tutorial goes past a single request and adds numbering, groups, notes, and parallel blocks.
If the question is "what do we store, and what points at what", use an ER diagram. Entities stand in for tables. PK and FK mark keys. The ends of a line say "one" or "many". When you already have CREATE TABLE statements, the SQL to Mermaid guide maps them. If the question is about classes and methods rather than rows, use a class diagram. Stuffing methods into an ER entity makes both diagrams worse.
If the question is "which states exist, and which events leave them", use a state diagram with stateDiagram-v2. Order status, ticket status, and a socket lifecycle fit. A flowchart can imitate this until two events leave the same state and the diamonds multiply.
If the question is "when", use a Gantt chart only when you have real dates that match dateFormat. A timeline is enough for an ordered list of events. If the question is "how does this split", use a mindmap, where indentation is the tree. Branch history belongs on a git graph. Amounts that move belong on a sankey or an XY chart. Neighbors of a system belong on a C4 diagram. Pie charts, quadrants, and the newer keywords are on the diagram types index.
Architecture, radar, treemap, and kanban render in current Mermaid and in the editor. A host on an older pin can reject them with an error that looks like a typo. Try the keyword on that host before you depend on it, or ship an SVG.
Keep one reader question per diagram. A flowchart with a sequence stuffed into a subgraph is two pictures. Split them. If you ask the AI diagram generator for a draft, name the type in the prompt so the model doesn't guess.
Mistakes that cost the first hour
The first hour goes to habits.
The whole system lands in one block. Forty nodes become a poster, lines cross, and the next edit shuffles the layout. Split by scenario: happy path, failure path, data model. Each one gets its own fence. The prose between the fences tells the reader why this picture is here.
The type follows an icon. A sequence diagram of a refund policy hides the decisions. A flowchart of an HTTP call hides who answered. If you are fighting the layout, switch types before you add invisible edges to force a shape.
Styling starts before the ids are stable. Get the edges right, then pick a theme. A hard-coded light fill is the usual reason text vanishes when a host applies a dark theme.
A paste from chat brings curly quotes, a non-breaking space, or a title sentence where the keyword should be. Retype quotes as straight " characters. Turn a title sentence into a %% comment or delete it. The keyword has to be the first statement, after any config.
Layout is not a promise. Adding a node can move a node you liked. Export SVG when you need a frozen poster, and expect the next text edit to place everything again.
Two keywords in one fence, or no fence at all, show up as a raw code block on the host. One keyword per fence, as many fences as you need. Preview in the editor before you push.
The source also drifts when someone commits a PNG and leaves the text on a laptop. Commit the text. Let the host render it, or generate the image in CI from that text.
When the failure is a line number, match it in the syntax guide. When the structure is the hard part, write five lines of plain language, name the type, and let the generator draft. Then edit the ids until they match the services and tables you actually have.
The diagram itself, separate from the library, is what is a Mermaid diagram. A map of the official docs is mermaid documentation. Picking a type before you draw is how to make a diagram.
Frequently asked questions
Is Mermaid free?
Yes. Mermaid is open source under the MIT license, and MermaidViewer's editor is free to use without an account.
Do I need to know JavaScript to use Mermaid?
No. You only write Mermaid's diagram syntax. JavaScript is only needed if you want to embed the Mermaid library in your own website.
Is Mermaid the same as Markdown?
No, but they work together. Mermaid has its own syntax, and many Markdown renderers display Mermaid when it is placed in a ```mermaid code block.