How to use Mermaid diagrams in Markdown

How do you add a Mermaid diagram to a Markdown file?

Start a fenced code block with three backticks followed by the word mermaid, write the diagram on the lines below, and close the block with three backticks. The first line inside the block names the diagram type: flowchart, sequenceDiagram, pie, gantt, timeline, mindmap, gitGraph and so on. Everything outside the block stays ordinary Markdown, so a diagram can sit between a heading and the paragraph that explains it. The copy buttons on this page include the fence.

Settings go at the very top of the block, between two lines of three dashes, before the diagram type: a title, or a config section that changes the theme or diagram options, as in the Gantt and git graph examples. Mermaid’s documentation notes that a misspelled setting is ignored silently while badly formed YAML breaks the diagram. Lines starting with %% are comments.

Where a platform does not render Mermaid, readers see the code block as text. Short labels and one statement per line keep that fallback readable, and an accTitle and accDescr help readers who use a screen reader where the diagram does render.

Does GitHub support Mermaid?

Yes. GitHub’s documentation page Creating diagrams says diagram rendering is available in GitHub Issues, GitHub Discussions, pull requests, wikis and Markdown files, which includes every README. You write a fenced code block with the mermaid language identifier, as on this page, and GitHub draws it when the file, issue or comment is viewed. Mermaid is one of four diagram syntaxes GitHub renders this way; the other three are GeoJSON and TopoJSON maps and ASCII STL 3D models, each with its own code block language.

For diagram types, GitHub’s page names flow charts, sequence diagrams and pie charts, then refers to the Mermaid documentation for the rest: whatever the Mermaid version GitHub runs can draw, GitHub draws, which with any Mermaid from 9.4 onwards includes the Gantt chart, timeline, mindmap and git graph above. GitHub does not publish that version, so render the info block from this page in an issue to see it, and expect a recently added option to lag there for a while. The same page warns that a third-party Mermaid browser plugin can cause errors on GitHub.

Which platforms render Mermaid in Markdown?

All of these use the same diagram code. What differs is how you insert it and which Mermaid version draws it, so a diagram that uses a recent option can render on one platform and fail on another.

Confluence and Mermaid

Confluence does not render Mermaid on its own. Its code block element highlights source code but has no Mermaid language, so a pasted fenced mermaid block stays text, and Atlassian’s guide to importing from Notion lists Notion’s Mermaid code blocks as arriving in Confluence as plain text.

Rendering comes from Atlassian Marketplace apps, which add a macro that takes Mermaid source, or a link to it, and draws the diagram on the page. Atlassian Labs publishes Mermaid diagrams viewer, which renders the Mermaid code found in a code block on the same page; Mermaid Chart, the company behind Mermaid, publishes Mermaid Chart for Confluence; and several other vendors list Mermaid macros for Confluence Cloud and Data Center. Apps are installed per site by a Confluence admin, so check which one your site has before writing a page around a diagram, then paste the same code you would use on GitHub into the macro.

Why does my Mermaid block show as code instead of a diagram?

Work through four checks. The fence must be tagged mermaid; a block with no language, or another language, is shown as ordinary code. The platform must render Mermaid at all; one that does not shows the block as code, which is the expected fallback. The diagram must parse; a syntax error stops the drawing, and depending on the platform you see an error message or the raw code. Paste the block into the Docs MD editor or another live preview to find the line that breaks.

Last, the platform’s Mermaid version must be new enough for what you used. Newer options fail on older renderers: the pie chart’s donutHole needs Mermaid 11.16.0 and the git graph’s BT: orientation 11.0.0. Render the info diagram above on the platform to see its version. Two platform-specific causes are documented: GitHub warns that a third-party Mermaid plugin can cause errors, and on GitLab Self-Managed a Cross-Origin-Resource-Policy header set to same-site or same-origin makes diagrams fail silently.

How do you share or export Markdown with Mermaid diagrams?

Inside a repository, the file is already the shared version: GitHub and GitLab draw the diagram for anyone who can open it. For readers outside the repository, paste the Markdown into the Docs MD editor and share it as a link; the shared page shows the rendered diagrams next to the text. The architecture diagram guide walks through a typical document.

For a file that has to travel as an attachment, convert the Markdown to PDF: the diagrams are drawn first and printed as vector graphics. To check a local file before sending it anywhere, open it in the Markdown viewer, which renders Mermaid in the browser without uploading the file.

Does GitHub support Mermaid in README files?

Yes. A README is a Markdown file, and GitHub renders fenced mermaid blocks in Markdown files as well as in issues, pull requests, discussions and wikis. Write the block as shown on this page, commit the file, and the diagram appears when the README is viewed on GitHub. GitHub chooses the Mermaid version it runs, so test newer syntax there; an info block shows the version.

How do you use Mermaid in Obsidian?

Type a fenced code block tagged mermaid in a note and write the diagram inside; Obsidian draws it in the note. Obsidian adds one extra: give flowchart nodes the class internal-link, as in class A,B internal-link;, and each node becomes a link to the note named by its text. Obsidian’s help notes that these links do not appear in the graph view. More syntax is on the Obsidian Markdown page.

Does Notion support Mermaid diagrams?

Yes, through code blocks. Type /code to add a code block, choose Mermaid in the language menu at its top left, and write the diagram. A second menu switches the block to Preview, which shows the chart, or Split, which shows code and chart together. Notion announced this in December 2021. You do not type the three-backtick fence yourself; the code block plays that role.

Does VS Code show Mermaid diagrams in the Markdown preview?

Yes, from VS Code 1.121, released in May 2026: the built-in Markdown preview renders mermaid blocks, and you can pan and zoom larger diagrams in place. On older versions, install an extension such as Markdown Preview Mermaid Support, which VS Code’s own extension guide uses as its example of adding Mermaid to the preview.

Which Mermaid diagram types work in Markdown?

Any type the platform’s Mermaid version supports, because the Markdown only carries the code. That includes the flowcharts, sequence diagrams, pie charts, Gantt charts, timelines, mindmaps and git graphs shown above, plus class, state and entity-relationship diagrams and newer types. Recently added types need a recent renderer, so a diagram that works in Docs MD can fail on a platform a few versions behind.