Guide
Writing diagrams as text with Mermaid
Mermaid lets you describe a diagram in a few lines of text and have it drawn automatically. Because the source is plain text, diagrams live next to the code, show up in diffs and are easy to update, which is why GitHub, GitLab, Notion and many documentation tools render Mermaid natively. This editor redraws the diagram as you type and exports it as SVG or PNG for places that do not.
How the syntax works
Every diagram starts with its type on the first line. A flowchart begins with flowchart TD (top-down) or LR (left to right), then lists nodes and arrows: A[Order placed] --> B{Payment OK?}. The bracket style sets the shape: square brackets for boxes, braces for decisions, round brackets for rounded boxes and [(...)] for a database cylinder. Text on an arrow goes between dashes, as in B -- Yes --> C. Indentation is optional but makes larger diagrams readable.
The diagram types in the templates
The Sequence template shows participants exchanging messages, with ->> for calls, -->> for replies and alt/else blocks for branches. Class diagrams list attributes and methods and draw composition and association. State diagrams model a lifecycle with [*] as start and end. Gantt charts take tasks with dates or durations and dependencies written as after w. Pie charts take labelled values, and mind maps use indentation alone to build the tree.
Live preview and errors
The preview redraws a moment after you stop typing. When the code has a mistake, Mermaid’s own parse error appears above the preview, usually naming the line and the token it did not expect, and the last drawing that worked stays on screen so you keep your bearings while fixing it.
A worked example
The Flowchart template describes an order process. A[Order placed] leads to the decision B{Payment OK?}, which branches to C[Reserve stock] on Yes and to D[Email customer] on No. C continues to a database node E[(Orders DB)] and a rounded F([Ship within 24 h]), while D leads to G[Cancel after 3 days]. The rendered SVG contains every label, including “Payment OK?”, and the SVG button saves it as diagram.svg.
Security and privacy
Diagrams pasted from elsewhere can contain links and click handlers. The editor runs Mermaid at its strict security level, which disables clicks, links and HTML labels, and then sanitises the generated SVG before showing it, so a diagram cannot run code on the page. The code you write is kept only in this browser’s storage, so a reload brings it back.
Where automatic layout stops
Mermaid places nodes for you, which is the point, but it offers limited control: you cannot drag a node or pin coordinates. For dense graphs, split the diagram, change the direction or use subgraphs. When you need a specific layout engine or fine control over ranks, Graphviz is the better tool.
Keeping diagrams maintainable
Give nodes short ids and put the readable text in the label, as in pay{Payment OK?}, so you can rename a step without touching every arrow that points to it. Group related steps in subgraph blocks with a title, and keep one diagram per idea rather than one giant chart; several small diagrams in a document are easier to update and review than a single dense one.
Related tools
- Graphviz Viewer renders DOT graphs with several layout engines.
- ER Diagram Maker draws database schemas from SQL.
- Markdown to HTML previews documentation around the diagram.
- SVG to PNG converts an exported SVG at a custom size.
Checked against the current version of the Mermaid Diagram Editor on .