What is a Mermaid diagram?

What is Mermaid?

Mermaid is an open-source JavaScript library that turns Markdown-inspired text definitions into diagrams. Its own documentation sums it up as a diagramming and charting tool whose main purpose is to help documentation keep up with development: because a diagram is text, it can live next to the code, be edited in a pull request and be regenerated whenever it changes, instead of going stale as an exported image. Mermaid was created by Knut Sveidqvist; the GitHub repository dates from November 2014, the code is MIT-licensed, and the project won the 2019 JS Open Source Award for the most exciting use of technology.

A Mermaid diagram, then, is the text itself. Each diagram begins with a keyword that names its type, such as pie, gantt or xychart-beta, followed by lines in that type’s small grammar. When a page that supports Mermaid displays the text, the library parses it and draws an SVG in its place. There is no image file to manage; change a line of text and the picture changes with it.

How does a Mermaid diagram get rendered?

In Markdown, the diagram goes in a fenced code block: three backticks and the word mermaid, the diagram text, three backticks. A platform that supports Mermaid recognises the fence and hands the text to the library; one that does not simply shows the code, which is still readable. The copy buttons on this page include the fence, so a pasted example works as is. The Mermaid in Markdown page walks through the embedding on each platform.

On a web page you control, you load the Mermaid script and it looks for elements with the class mermaid, or you call its render function yourself. Mermaid’s documentation also provides the Live Editor at mermaid.live for drafting a diagram and seeing it drawn as you type. Docs MD does the same inside the editor: paste Markdown with a mermaid block into the editor and the preview, the shared link and the PDF export all show the drawn diagram.

Which diagram types does Mermaid have?

Mermaid 11.16 documents about thirty diagram types. They fall into two families. Chart-style types show data or plans and are the ones illustrated above; Docs MD has a full page of copyable examples for each. UML-style types describe software structure and behaviour and are covered with worked examples on chartcraft.dev. A few further types, such as C4, requirement, block, packet, architecture and treemap diagrams, are documented at mermaid.js.org.

Where do Mermaid diagrams render?

In more places each year, which is the main reason to learn the syntax once. GitHub renders mermaid blocks in issues, pull requests, discussions, wikis and Markdown files. GitLab renders them in its Markdown and states in its documentation which Mermaid major version it supports. Notion added Mermaid to its code block in December 2021: choose Mermaid as the language and switch the block to preview. Obsidian renders mermaid code blocks in notes, and VS Code’s built-in Markdown preview renders them from version 1.121, where earlier versions needed an extension. Mermaid’s own integrations list marks Azure DevOps wikis as native support and lists several Marketplace apps that add Mermaid to Confluence and Jira.

The catch is the version. Each platform ships its own copy of Mermaid and updates on its own schedule, so a diagram type or option added recently, such as kanban in 11.4.0 or radar charts in 11.6.0, renders on one platform and shows as code or an error on another. GitHub’s documentation suggests rendering the one-word info diagram to see the version in use; the Mermaid in Markdown page shows that check. When the audience is outside those tools, paste the Markdown into the Docs MD editor and share the link; the shared page renders every diagram with Mermaid 11.16.

Is Mermaid free to use?

Yes. Mermaid is open source under the MIT licence, which allows use, modification and redistribution, including in commercial products, with attribution. The library is published on npm and served from public CDNs, and the Live Editor at mermaid.live is free to use. The team behind the project also offers a hosted product, Mermaid Chart, but the library and syntax do not depend on it.

What is the difference between a Mermaid diagram and an image?

A Mermaid diagram is text, so it can be edited in any editor, reviewed in a pull request, searched, and regenerated automatically when the source changes; an image has to be redrawn in a graphics tool and re-exported. The trade-off is control: Mermaid lays the diagram out for you, and you adjust it through options rather than by dragging shapes. For diagrams that live next to code or in documentation, that trade is usually worth it.

Do I need to install anything to use Mermaid?

Not on a platform that already supports it. Write the diagram in a mermaid code block in GitHub, GitLab, Notion, Obsidian, VS Code or the Docs MD editor and it is drawn for you. You only install Mermaid, from npm or a CDN script tag, when you want diagrams on your own website or in a build pipeline. The Live Editor at mermaid.live needs nothing installed either.

Which Mermaid diagram should I use?

Start from the data. Shares of one whole: pie chart. Amounts by category: bar chart. Tasks with dates: Gantt chart. Events in order: timeline. Ideas around a topic: mindmap. Items ranked by two judgements: quadrant chart. Flows of quantities: sankey diagram. Work by status: kanban. Items compared across criteria: radar chart. Steps a person takes: user journey. For processes with decisions, message exchanges, classes, states or database tables, use the UML types; the table above links to examples of each.

Why does my Mermaid diagram render in one tool but not another?

Almost always the Mermaid version. Each platform bundles its own copy, and recently added types and options are not available on an older copy: kanban needs 11.4.0, radar charts 11.6.0, the pie chart’s donut option 11.16.0. Render the info diagram on the platform to see its version, and prefer the older spellings, such as xychart-beta, when a document must work everywhere. A second cause is a third-party Mermaid browser plugin, which GitHub’s documentation warns can cause errors on its pages.