What is Mermaid? A Beginner's Guide to Diagrams as Code

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.

mermaidCopy

flowchart LR
    T[Text you write] --> M((Mermaid)) --> D[Diagram you share]

Open in the live editor

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 --> B is 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 --> Start

Paste 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

1. Open the free online Mermaid editor — no sign-up needed.
2. Pick a template or a sample for the diagram type you need.
3. Edit the text on the left and watch the preview update live.
4. Export to PNG, SVG or PDF, copy the Markdown, or create a share link.