Mermaid works in most tools developers and teams already use. Here's how to use it in the most popular ones — and what to do when a tool doesn't support it.
Notion
Type /code, choose Mermaid as the language and paste your diagram. Switch the block view to Preview or Split to see it rendered. Notion's Mermaid version can lag behind the latest release, so test new diagram types first.
Obsidian
Obsidian renders ```mermaid code blocks in reading and live preview modes out of the box — perfect for knowledge bases and study notes.
Confluence
Confluence Cloud needs a marketplace app for Mermaid. Alternatively, publish a diagram from MermaidViewer and embed its share link with an iframe macro, or export an SVG/PNG and attach it.
VS Code
VS Code's built-in Markdown preview supports Mermaid through extensions such as "Markdown Preview Mermaid Support". For a faster loop with AI help and exports, keep MermaidViewer open side by side.
Docs frameworks
- Docusaurus — enable
@docusaurus/theme-mermaid. - MkDocs Material — supports Mermaid in
superfencescode blocks. - VitePress / Astro / Next.js — use a Mermaid plugin or render client-side with the mermaid package.
Embedding MermaidViewer diagrams anywhere
Signed-in users can make a diagram public and copy an embed code (an iframe). The embed always shows the latest saved version, so updating the diagram updates every page that embeds it.
What Cloud renders on its own
If you came here for mermaid in confluence, the short version on the rest of this page is the whole native story: Confluence Cloud does not draw a mermaid fence. The code macro highlights text. It does not run the Mermaid library. You paste a flowchart, switch to the published view, and you still see the source. That is expected, and it is why teams pick one of three workarounds.
This page is about Cloud. A Data Center or Server site can ship different macros, so ask the admin which of these paths exist there before you write a runbook that assumes Cloud's limits.
The three paths are a Marketplace app, an iframe of a diagram you published from MermaidViewer, and an image you attach to the page. They solve different problems. An app keeps the source on the Confluence page. An iframe keeps a single saved diagram updated everywhere it is embedded. An attachment stays inside Confluence's permissions and still works when macros and remote frames are locked down.
Notion, Obsidian, and VS Code are different products with their own steps. Use Mermaid in Notion, Mermaid in Obsidian, and Mermaid in VS Code for those. Don't copy their fence instructions onto a Confluence page and expect a picture.
A Marketplace app
The Atlassian Marketplace has apps that add a Mermaid macro to Cloud. This guide calls that option "a Marketplace app" on purpose. Apps change, pricing changes, and a feature list copied here would go stale. Evaluate the current listing yourself: who publishes it, what data it sends off the site, and whether your admin will approve it.
Install is an admin action on most sites. A user who can edit a page often cannot add an app. Write the request as a workflow, not as a syntax question. Name the pages that need diagrams, say the source should stay editable on the page, and link the listing. If the admin says no, you still have the embed and the attachment. Don't block a design doc on an install.
Once an app is installed, the people editing the page need a one-paragraph convention: where the macro sits, who updates it, and what to do when the macro shows an error. The error is still a Mermaid parse error. Paste the source into the editor and use the syntax guide. The app is a host. It doesn't make end mean something new.
Prefer an app when the editors live in Confluence and will not open a repo or another tool. The source sits in the page history, which is the closest Cloud gets to a diff for people who don't use Git. Prefer something else when the diagram already lives next to the code. Two copies, one in the repo and one in the macro, drift. Pick the repo as the source and publish a view into Confluence.
Embed a published diagram
Signed-in users can make a MermaidViewer diagram public and copy an embed code. The embed is an iframe. The frame shows the latest saved version, so an edit in the editor updates every page that embeds that diagram. You don't re-upload a picture after each rename.
On Confluence Cloud, paste that iframe into the iframe macro if your site allows the macro and allows the diagram's domain. Many sites disable the iframe macro, or they allow it only for domains an admin has listed. A blank frame usually means the macro is off or the domain is not allowed. It does not mean the Mermaid source is wrong. Open the embed URL in a browser tab. If the diagram is there, the block is Confluence's allowlist. Ask an admin to permit the domain, or switch to an attachment.
Treat the embed as public. Publishing the diagram makes it available to anyone with the URL, which is a different audience from the Confluence page. Don't embed a chart that contains customer data, internal hostnames you wouldn't put in a public repo, or an unreleased incident timeline. If the chart has to stay behind Confluence permissions, use an attachment. The iframe will not inherit the page's restrictions.
Free and Starter embeds include a small badge. Pro embeds do not. The badge is a corner mark, not a change to the diagram text. If a printed page can't have it, export a file instead of embedding. Details of the plans are on pricing.
Width is the other practical limit. Confluence's content column is narrower than a fullscreen editor. A left-to-right chart with eight nodes overflows or shrinks until the labels are dots. Split the chart, or switch the direction to TD, before you blame the macro. Set the iframe height so the caption isn't clipped. A height that looked fine for a tiny example will crop a sequence diagram. Check the published page, not only the editor chrome.
When the source of truth is the repo, link the repo file in the paragraph under the frame. The iframe is the view. The file is what a pull request changes. Say that in one sentence so the next editor doesn't "fix" the diagram inside a screenshot.
Attach an SVG or a PNG
Attaching a file is the path that survives a strict site. Export from the Mermaid to SVG converter or the Mermaid to PNG converter, upload the file to the page, and place it in the body. Use SVG when the site accepts it and the labels stay sharp on a large monitor. Use PNG when an SVG upload is stripped or sanitized. Some configurations treat SVG as active content and refuse it. A PNG at 2× or 4× on Starter, or up to 8× on Pro, is the fallback that still looks clean. SVG download is on Pro. Free PNG is 1× with a watermark. Scale and background are covered in the export guide. Export a white background for a Confluence page that is white. A transparent PNG can pick up a dark panel and hide the lines.
Write alt text on the image. "Charge path from checkout UI to ledger" tells a screen reader what the pixels are. The file name diagram-final-v3.png does not. Repeat the decision in a sentence above the image so the page still makes sense if the attachment fails to load.
Attachments follow the page's permissions. That is the reason to choose them for anything that isn't public. The cost is freshness. The image does not update when you edit the source. Someone has to export and upload again. Put the .mmd text on the page as a code block, or link the repo file, so the next person can regenerate. A code block on Cloud will show the text. It will not render. Label it "source, not a picture" so readers don't file a bug against the highlighter.
PDF is the better attachment when the page itself will be exported or printed. The Mermaid to PDF converter makes a vector page sized to the diagram. Attach it, and also keep the SVG if the on-page view should be an image. Two files, one source.
Add the date or the git revision in the caption. "Exported from docs/checkout.mmd at a1b2c3d." When the picture and the code disagree, the caption says which one you trusted on that day.
Keep a single source
Whichever path you pick, write down the source of truth at the top of the page. "Edited in the Mermaid macro on this page." "Edited in MermaidViewer, embedded here." "Edited in docs/checkout.mmd, image attached." Three sentences, one of them true. The failures we see are pages that do all three and match none.
If the diagram describes code, the repo wins. The Confluence page holds a view and a link. Reviewers already have a pull request. A second editor inside Confluence guarantees drift by the next sprint.
If the diagram describes a policy that product and support edit, Confluence should win, which means an app or a careful attachment routine. Don't make those editors learn a fence they can't preview on the page. Let them edit where the preview works, then publish.
Secrets stay out of all three. A public embed leaks them to the URL. An attachment leaks them to anyone who can view the page, which may be a large group. A macro stores them in page history, where they are hard to purge. Describe the flow with placeholder names.
flowchart TD
Q{Who edits the source?}
Q -->|People in Confluence| App[A Marketplace app]
Q -->|One saved diagram, many pages| Frame[Iframe of a published diagram]
Q -->|Must stay inside page permissions| File[Attach SVG or PNG]Revisit the choice when the admin changes macro policy. A blank iframe after a security review is your signal to attach a PNG the same day, not to debug the Mermaid text you already previewed in the editor.
Several diagrams on one page need labels that say which scenario each one is. "Checkout" and "Refund" as headings, then the frame or the image, then one sentence. A gallery of untitled pictures is how a support agent follows the happy path during an incident. If the page is already long, link out to child pages instead of stacking six iframes. Each iframe is another remote load, and a reader who prints the page to PDF will wait on all of them or get blank boxes. For a page you know will be printed, attach the PDF or PNG exports and skip the live frames.