What is Mermaid and why use it instead of a drawing tool?

Mermaid lets you describe a diagram in text and have it rendered automatically. Compared with a drag-and-drop tool, the source is versionable, reviewable in a pull request and editable by anyone with a text editor, and the diagram is regenerated from the text so it cannot silently go stale. It is the de facto standard for diagrams in developer documentation because GitHub, GitLab, Notion and Obsidian render it natively.

Which diagram types can I make?

The templates cover flowchart, sequenceDiagram, classDiagram, stateDiagram-v2, erDiagram, gantt and pie. Because the preview uses the complete Mermaid library, other supported types such as journey, mindmap, timeline, gitGraph and quadrantChart also render if you paste their syntax; they simply do not have a starter template.

How do I put the diagram in a GitHub README?

Click "Copy code" and paste the Mermaid source into your Markdown file inside a fenced block that starts with ```mermaid and ends with ```. GitHub has rendered these blocks since 2022, and GitLab, Bitbucket, Notion, Obsidian and Azure DevOps do the same. Reviewers then see the diagram in the rendered view and the text diff in the code view.

How do I save the diagram as an image?

Use "Save SVG" for a vector file that scales without blur, ideal for documentation sites and print, or "Save PNG" for a raster image rendered at double resolution on the dark theme background, which is convenient for chat tools, email and slide decks. "Copy SVG" puts the SVG markup on your clipboard if you want to inline it in HTML.

How are arrows written in a sequence diagram?

Declare participants with participant A as Alias, then write messages as Sender->>Receiver: text. A solid arrow is ->>, a dashed reply is -->>, and activate/deactivate draws the lifeline bars. A participant can message itself with A->>A: text. The sequence template shows a login flow with these basics that you can adapt.

How do I express relationships in an ER diagram?

Use the crow's-foot notation: USER ||--o{ ORDER : places means one user places zero or more orders. The symbols are || for exactly one, o{ for zero or more, |{ for one or more and o| for zero or one. Attributes go in a block such as USER { string id PK } and can be tagged PK or FK. The ER template models users, orders, order items and products as a starting point.

How do I change node shapes in a flowchart?

The brackets decide the shape: A[text] is a rectangle, B(text) has rounded corners, C{text} is a decision diamond, D((text)) is a circle, E>text] is a flag and F[/text/] is a parallelogram. Arrows can be --> solid, -.-> dotted or ==> thick, and a label is added with A -->|label| B. The flowchart template contains a decision branch you can extend.

Why does the preview show a syntax error?

The message comes straight from the Mermaid parser and usually names the line. The most common causes are forgetting the diagram type on the first line (flowchart TD, sequenceDiagram and so on), using a reserved word such as end or class as an identifier, a message in a sequence diagram that references an undeclared participant, and stray full-width or non-breaking spaces from a copy-paste. Fix the reported line and the diagram re-renders immediately.

Does the editor keep my work if I close the tab?

Yes. The current code is saved to your browser's local storage on every change and restored when you return, in the same browser on the same device. There is no cloud sync or account; if you need the diagram elsewhere, copy the code or download the SVG. The Clear button empties the editor after a confirmation.

Is my diagram code uploaded anywhere?

No. The Mermaid library runs inside your browser and renders the SVG locally; your diagram code is never sent to a server. You can safely draft confidential system architectures, database schemas, internal process flows and unreleased project timelines.

Mermaid Preview

Write Mermaid code and preview flowcharts, sequence, class, state, ER, Gantt and pie diagrams live. Export SVG or PNG. Runs entirely in your browser.

A split-pane editor for diagrams as code: type Mermaid on the left, watch the rendered diagram update on the right, then drop the code into a README, a pull request or a design doc where GitHub, GitLab, Notion or Obsidian will render it natively. Seven starter templates get you from a blank page to a real flowchart, sequence diagram or ER diagram in seconds, and your work is kept in the browser between visits.

Mermaid Preview

// Mermaid Preview: Features

What Mermaid is

Mermaid is a text syntax for diagrams. A few lines such as flowchart TD, A[Start] --> B{Ready?} describe boxes, arrows and layout, and a renderer turns them into an SVG. Because the source is plain text, diagrams live next to code, show meaningful diffs in pull requests and never drift out of date the way exported images do. GitHub, GitLab, Bitbucket, Notion, Obsidian, Confluence and Azure DevOps all render ```mermaid fences in Markdown without any plugin.

Diagram types and templates

One-click templates are provided for flowcharts, sequence diagrams, class diagrams, state diagrams (stateDiagram-v2), entity-relationship diagrams, Gantt charts and pie charts. Each template is a complete, valid example that you can edit rather than a snippet, so you learn the syntax by changing something that already works. The renderer is the full Mermaid library, so other diagram kinds it supports, such as user journeys, mindmaps, timelines and git graphs, also preview correctly if you paste their code.

Live preview with clear error messages

Every keystroke re-renders the diagram, and the preview keeps the last good result while you type. When the parser rejects the input, the error text from Mermaid appears in the preview pane, usually with the line number and the token it did not expect, which is far quicker than round-tripping through a Markdown viewer. Typical culprits are a missing diagram declaration on the first line, a reserved word such as end used as a node ID, or an undeclared participant in a sequence diagram.

Export to SVG or PNG

Download the current diagram as an SVG file for crisp scaling in web pages, PDFs and print, or as a PNG rendered at 2x resolution on the dark background for pasting into Slack, email or slides. You can also copy the raw SVG markup, or copy the Mermaid source to paste into a ```mermaid block in Markdown. Sequence diagrams of authentication flows pair well with the JWT Decoder when you document what each token carries at every hop.

Saved locally, never uploaded

The code in the editor is stored in your browser's local storage, so reloading or closing the tab does not lose your work. Rendering happens entirely on your machine with Mermaid's strict security level, and nothing you type is sent to a server. That makes it safe to sketch internal architectures, database schemas and unreleased product flows. Network diagrams that reference address ranges can be checked against the Subnet Calculator before you commit them to a document.

// Mermaid Preview: FAQ

What is Mermaid and why use it instead of a drawing tool?: Mermaid lets you describe a diagram in text and have it rendered automatically. Compared with a drag-and-drop tool, the source is versionable, reviewable in a pull request and editable by anyone with a text editor, and the diagram is regenerated from the text so it cannot silently go stale. It is the de facto standard for diagrams in developer documentation because GitHub, GitLab, Notion and Obsidian render it natively.
Which diagram types can I make?: The templates cover flowchart, sequenceDiagram, classDiagram, stateDiagram-v2, erDiagram, gantt and pie. Because the preview uses the complete Mermaid library, other supported types such as journey, mindmap, timeline, gitGraph and quadrantChart also render if you paste their syntax; they simply do not have a starter template.
How do I put the diagram in a GitHub README?: Click "Copy code" and paste the Mermaid source into your Markdown file inside a fenced block that starts with ```mermaid and ends with ```. GitHub has rendered these blocks since 2022, and GitLab, Bitbucket, Notion, Obsidian and Azure DevOps do the same. Reviewers then see the diagram in the rendered view and the text diff in the code view.
How do I save the diagram as an image?: Use "Save SVG" for a vector file that scales without blur, ideal for documentation sites and print, or "Save PNG" for a raster image rendered at double resolution on the dark theme background, which is convenient for chat tools, email and slide decks. "Copy SVG" puts the SVG markup on your clipboard if you want to inline it in HTML.
How are arrows written in a sequence diagram?: Declare participants with participant A as Alias, then write messages as Sender->>Receiver: text. A solid arrow is ->>, a dashed reply is -->>, and activate/deactivate draws the lifeline bars. A participant can message itself with A->>A: text. The sequence template shows a login flow with these basics that you can adapt.
How do I express relationships in an ER diagram?: Use the crow's-foot notation: USER ||--o{ ORDER : places means one user places zero or more orders. The symbols are || for exactly one, o{ for zero or more, |{ for one or more and o| for zero or one. Attributes go in a block such as USER { string id PK } and can be tagged PK or FK. The ER template models users, orders, order items and products as a starting point.
How do I change node shapes in a flowchart?: The brackets decide the shape: A[text] is a rectangle, B(text) has rounded corners, C{text} is a decision diamond, D((text)) is a circle, E>text] is a flag and F[/text/] is a parallelogram. Arrows can be --> solid, -.-> dotted or ==> thick, and a label is added with A -->|label| B. The flowchart template contains a decision branch you can extend.
Why does the preview show a syntax error?: The message comes straight from the Mermaid parser and usually names the line. The most common causes are forgetting the diagram type on the first line (flowchart TD, sequenceDiagram and so on), using a reserved word such as end or class as an identifier, a message in a sequence diagram that references an undeclared participant, and stray full-width or non-breaking spaces from a copy-paste. Fix the reported line and the diagram re-renders immediately.
Does the editor keep my work if I close the tab?: Yes. The current code is saved to your browser's local storage on every change and restored when you return, in the same browser on the same device. There is no cloud sync or account; if you need the diagram elsewhere, copy the code or download the SVG. The Clear button empties the editor after a confirmation.
Is my diagram code uploaded anywhere?: No. The Mermaid library runs inside your browser and renders the SVG locally; your diagram code is never sent to a server. You can safely draft confidential system architectures, database schemas, internal process flows and unreleased project timelines.

// How to Use Mermaid Preview

Start from a template

Choose a diagram type from the Samples row: flowchart, sequence, class, state, ER, Gantt or pie. The template code is placed in the editor on the left and the rendered diagram appears on the right, so you can see the syntax and its result together.
Edit and watch the preview update

Change node names, add arrows, attributes or steps, and the diagram re-renders as you type. If something does not parse, the Mermaid error message appears in the preview pane with the line to fix.
Export or embed the result

Download the finished diagram with "Save SVG" or "Save PNG", copy the SVG markup for direct embedding, or use "Copy code" and paste the source into a ```mermaid block in your README, wiki or issue where it will render natively.

Category Design