Mermaid diagram examples

Which Mermaid chart for which data?

Mermaid has a type for most things a document needs to show. The chart-style types take data or plans; the UML-style types describe software. Pick by the shape of your data, not by the look of the chart. Three types that did not fit above have their own example pages: kanban for work by status, radar chart for items compared across criteria, and user journey for the steps a person takes and how each one feels.

How do you use these examples?

Each copy button on this page copies the example wrapped in a fenced code block tagged mermaid, which is the form GitHub, GitLab, Obsidian, Notion and VS Code recognise. Paste it into a README, an issue, a note or a wiki page and the platform draws the diagram. Then edit the labels and numbers in place; because the diagram is text, the picture follows. The Mermaid in Markdown page shows the embedding on each platform and how to check which Mermaid version a platform runs.

To share a rendered diagram with people who are not in your repository or workspace, paste the Markdown into the Docs MD editor and send the link: the shared page renders every mermaid block with Mermaid 11.16 and prints cleanly, and PDF export draws the diagrams before converting. The architecture diagram guide walks through a typical document with several diagrams.

Which Mermaid version do the examples need?

Every example on docs-md.com is rendered with Mermaid 11.16 and uses syntax taken from Mermaid’s documentation for that version. Most of the types are old enough to work everywhere: pie, Gantt, git graph and user journey predate Mermaid 10, timeline and mindmap are from 9.x, the quadrant chart from 10.2.0, sankey from 10.3.0 and the XY chart from 10.6.0. Two are recent: kanban needs 11.4.0 and the radar chart 11.6.0.

Individual options are often newer than their chart. The pie chart’s donutHole needs 11.16.0, bar chart data labels 11.14.0, and the sankey node options 11.15.0; each example page notes the version next to the option. Where it matters, the examples use the older spellings xychart-beta and sankey-beta, which every version since the chart was introduced accepts, rather than the suffix-free keywords that only work from 11.10.0.

What else can Mermaid draw?

Beyond the types on this page, Mermaid 11.16 documents C4, requirement, block, packet, architecture, treemap and ZenUML diagrams, and several newer experimental types. For a diagram that does not fit any of these, a flowchart is the usual fallback: it has the most shapes and the most control over layout. The What is a Mermaid diagram page explains how the library works and where it renders; Mermaid’s own syntax reference lists every type with its current status.

Can I use these Mermaid examples in GitHub README files?

Yes. GitHub renders fenced mermaid blocks in Markdown files as well as in issues, pull requests, discussions and wikis, and the copy buttons include the fence. GitHub chooses the Mermaid version it runs, so the newer types (kanban, radar) and newer options may not render there yet; its documentation suggests an info block to see the version. The older types on this page render on any version that supports Mermaid.

Which Mermaid chart is best for comparing numbers?

A bar chart, written with the XY chart type. Put the categories on the x-axis and the values in a bar list; use a line list for change over time, or both for actual against target. Use a pie chart only when the numbers are parts of one whole, and a radar chart when you compare a few items across several criteria that share one scale.

Does Mermaid have a bar chart?

Yes, as part of the XY chart type introduced in Mermaid 10.6.0. The keyword is xychart-beta (or xychart from 11.10.0), and a bar [...] statement draws the bars; line [...] draws a line on the same axes, and horizontal after the keyword turns the bars sideways. The bar chart examples page shows vertical and horizontal bars, data labels and colours.

Where are the flowchart and sequence diagram examples?

On chartcraft.dev, which covers the UML-style Mermaid types: flowchart, sequence, class, state and entity relationship diagrams, each with worked examples. Docs MD focuses on the chart-style types that show data and plans, and on using Mermaid inside Markdown. The table above links to both sets so you can pick the right type first.

How do I check which Mermaid version a platform runs?

Render the one-word diagram info in a mermaid code block on that platform; it draws the version number in place of a diagram. GitHub’s documentation recommends this check. Compare the result with the version noted on each example page before using a newer type or option, and prefer xychart-beta and sankey-beta over the suffix-free keywords when the version is old or unknown.