Ready-to-use Mermaid diagrams — visual, copy-paste

How Mermaid diagrams work in Markdown

Mermaid is a text-to-diagram language born at SAP and now maintained by an active open-source community. You write a diagram as plain text inside a Markdown code fence with the language tag mermaid — the renderer turns it into an SVG diagram at view time:

```mermaid
flowchart LR
  A[Start] --> B[Done]
```

Same source. Every platform. No image hosting, no asset pipeline, no broken links when you rename a section.

Why Mermaid won

Before Mermaid, technical writers had three choices: hand-draw a diagram in a UI tool and embed the exported PNG (impossible to diff, hard to keep in sync), use a heavy authoring app like Lucidchart or Draw.io (paid, requires manual sync), or skip the diagram entirely and describe the flow in prose. Mermaid removed all three trade-offs:

• Plain text in version control. A line-level diff shows exactly what changed in a flowchart — same as code.
• Renders inline on every Markdown platform. GitHub, GitLab, Notion, Docusaurus, Obsidian — pick a platform; if it speaks Markdown, it speaks Mermaid.
• One source for docs and slides. The same diagram code can be embedded in a README, a Slidev deck, and a Jupyter notebook.
• AI-friendly. Tell ChatGPT "give me a Mermaid sequence diagram for a login flow" and you get exactly what you need.

Where it renders

Platform	Mermaid support
GitHub README / issues / PRs	Built-in since 2022
GitLab Markdown	Built-in
Bitbucket Cloud	Built-in
Notion	Embed block
Obsidian	Built-in
Joplin	Built-in
Docusaurus	@docusaurus/theme-mermaid
MkDocs Material	pymdownx.superfences
Hugo	Mermaid shortcode
Astro	rehype-mermaid
Markdown Viewer editor (this one)	Live, in the preview pane

The 12 diagram types

Type	Use for
Flowchart	Processes, decisions, system architectures
Sequence	API calls, message exchanges, login flows
Class	OO domain models, type hierarchies
State	Finite state machines, order lifecycles
ER	Database schema, entity relations
Gantt	Project timelines, sprint planning
Pie	Quick percentage breakdowns
Mindmap	Brainstorms, taxonomies
Timeline	Roadmaps, history
Journey	User journey mapping with satisfaction scores
Git graph	Branching workflows
Quadrant	Impact-vs-effort and similar 2×2 matrices

Quick syntax pointers

• Direction in flowcharts: LR (left to right), TD (top down), BT (bottom up), RL (right to left).
• Node shapes: [Text] rectangle, (Text) rounded, {Text} rhombus (decision), ((Text)) circle, [(Text)] cylinder (database), [[Text]] subroutine, [/Text/] parallelogram (I/O).
• Edge types: --> solid arrow, -.-> dashed, ==> thick, -- label --> labeled, --- open line.
• Subgraphs: subgraph Title … end groups nodes inside a container.
• Comments: %% comment (line is ignored by parser).
• Init directives: %%{init: {'theme':'dark'}}%% at the top to set theme and other options.
• Always validate. Use the Mermaid Validator before committing — invalid syntax silently fails to render on most platforms, leaving raw text in your README.

Workflow tips

1. Start from a template. Browse the gallery below for a diagram type that matches your shape, then mutate labels and structure.
2. Live-edit in our editor. The Markdown Editor preview pane re-renders Mermaid as you type. Way faster than the GitHub edit-commit-refresh loop.
3. Validate before commit. A single typo in production Markdown means an unrendered diagram on your README — verify with the Mermaid Validator or our Diagram Inventory tool.
4. Audit a docs repo. When migrating Markdown between platforms, the Code Block Extractor pulls every ```mermaid fence out of a document so you can verify each one renders on the new host.
5. Pair with math. For technical content combining diagrams and equations, see the Math Equation Inventory for KaTeX/LaTeX templates.

Why use templates instead of writing from scratch?

A blank mermaid fence is intimidating. The syntax for sequence diagrams vs flowcharts vs ER diagrams is different — same library, different mini-languages. Templates give you:

• A working starting point. Copy, mutate. No need to remember whether sequenceDiagram needs participant or actor.
• Reference syntax in context. Want a decision node? Look at the flowchart-with-decision template.
• Time savings. Most teams use only 4-5 diagram types regularly. The catalog covers every common case so you stop Googling "mermaid syntax cheat sheet" every other week.

Companion tools

• Mermaid Validator — lint your custom diagrams before committing.
• Markdown Editor — write diagrams live with side-by-side preview.
• Math Equation Inventory — same idea, for LaTeX equations.
• Markdown Code Block Extractor — pull every ```mermaid fence out of a document.
• Markdown Outline Reorder — restructure a doc that contains diagrams without losing them.
• GFM Compliance Checklist — confirm fenced code declares languages.