# Paste Mermaid Diagrams into Confluence — Now on Mermaid 12 September 28, 2026 · 9 min read [NGPilot](https://ngpilot.com) Quick Answer Confluence's editor is WYSIWYG and has no Mermaid renderer, so pasting a Markdown file that contains ` ```mermaid ` fences imports them as plain code blocks — the diagrams arrive dead. Paste into a Markdown macro instead: [**Enhanced Markdown for Confluence**](https://marketplace.atlassian.com/apps/1237026/enhanced-markdown-for-confluence/) renders Mermaid 12 inline, so a whole README pastes in and the diagrams come alive. The v12 upgrade is what makes this newly worthwhile — **UML use case diagrams** now survive the paste, which is the diagram type requirements docs kept losing. What you'll learn 1. Why Mermaid dies on the way into Confluence, and where the fix lives 2. The paste workflow: repo Markdown in, rendered diagrams out 3. What Mermaid 12 changes — use case diagrams, refreshed layout, richer ZenUML 4. What happens to diagrams you already published The diagrams live in the repository. They were written in Mermaid, they are reviewed in pull requests next to the code they describe, and they are correct as of the last commit. The documentation, however, lives in Confluence — because that is where the rest of the team reads it. So somebody copies a Markdown file across, pastes it into a Confluence page, and the flowcharts, sequence diagrams and ER models arrive as grey boxes of unrendered code. Everyone has hit this. It is one of the most common Confluence complaints, and the usual workarounds are worse than the problem: export every diagram to PNG and re-upload them (now they rot), keep the diagrams in an external tool and paste links (readers need a second account, and the links break), or build a browser extension to force rendering on paste. There is a better answer, and Mermaid 12 makes it better still. ## Why Mermaid dies on the way into Confluence[​](#why-mermaid-dies-on-the-way-into-confluence "Direct link to Why Mermaid dies on the way into Confluence") Two separate problems, often confused: **Confluence cannot render Mermaid at all.** There is no built-in Mermaid support in the editor — no `/mermaid` macro, no diagram fence handling. Anything that looks like a diagram arrives as a code block. This is a product limitation, not a configuration mistake, and it is why [Mermaid rendering in Confluence needs an app](/blog/does-confluence-support-mermaid.md) rather than a setting. **The import path actively flattens your content.** When Markdown containing fenced diagrams is pasted or imported, the fence is treated as a code block and the page stores it as text. The information is not lost, but it is no longer a diagram — and nothing on the page will ever turn it back into one. This is why "just paste the Markdown" does not work, and why teams end up screenshotting their diagrams. ## The fix: paste into a Markdown macro[​](#the-fix-paste-into-a-markdown-macro "Direct link to The fix: paste into a Markdown macro") [Enhanced Markdown for Confluence](https://marketplace.atlassian.com/apps/1237026/enhanced-markdown-for-confluence/) is a Markdown editor that lives inside the page. Paste your file into it and the Quikdown engine renders everything as you type — headings, GFM tables, syntax-highlighted code, KaTeX and LaTeX math, and Mermaid diagrams. The workflow is three steps: 1. **Insert the macro.** Type `/enhanced markdown` in the Confluence editor and pick the app. You get a split view: Markdown source on the left, live preview on the right. 2. **Paste the whole file.** Not just the diagram — the entire document. Tables, code fences, math and diagrams all render in the preview, so the page keeps one consistent look instead of a mix of pasted screenshots and live text. 3. **Check the preview, then save.** Diagrams render as centered inline SVG and update live as you keep typing. On save, the Markdown is stored as standard Confluence storage format, so it participates in search, exports, page history and permissions like any other page content. Two properties matter for teams beyond the first paste. The Markdown stays **re-editable source on the page**, so updating a diagram later means changing a line — not re-importing the file. And because the rendering libraries are bundled locally rather than pulled from a CDN, the macro stays inside your Atlassian boundary, which matters when "Runs on Atlassian" is a procurement checkbox. ## What's new in Mermaid 12 for pasted docs[​](#whats-new-in-mermaid-12-for-pasted-docs "Direct link to What's new in Mermaid 12 for pasted docs") Enhanced Markdown now runs **Mermaid 12**, and for the paste workflow the headline is not cosmetic. **UML use case diagrams (`usecase-beta`).** This is the diagram type that requirements documents need and Markdown could not previously express. Actors, `systemBoundary` blocks, `include`/`extend` relationships and notes all render — so a requirements doc pasted from the repo arrives with its use case diagram intact instead of as an image or a footnote. **A refreshed default look.** Mermaid 12 changes the default layout engine and colour palettes, so flowcharts, state diagrams and class diagrams come out looking better with no code change. **Richer ZenUML.** ZenUML fences now support conditionals (`if/else`), loops (`while`), parallel blocks (`par`) and `try/catch` — useful when the sequence diagram you want is more than a straight list of messages. **Centered, live SVG.** Diagrams render centered inline and update as you edit, so a diagram that is too wide is obvious while you are writing rather than after you have pasted the whole file. The full Mermaid 12 picture, including the syntax for every new type, is in [Mermaid 12 in Confluence & Jira](/blog/mermaid-12-confluence-jira.md). ## Copy-paste: a requirements doc with a v12 use case diagram[​](#copy-paste-a-requirements-doc-with-a-v12-use-case-diagram "Direct link to Copy-paste: a requirements doc with a v12 use case diagram") This is the block to paste into the Markdown source. It is the use case diagram that could not be expressed in Markdown before v12: ```` ## Checkout use cases ```mermaid usecase-beta direction LR actor Customer actor Admin systemBoundary Store("Online Store") UC1("Browse Products") UC2("Checkout") end Customer --> UC1 Customer --> UC2 Admin --> UC2 UC2 ..> : include UC1 Admin --|> Customer note for UC1 "Available 24/7" ``` ```` The preview shows actors connected to use cases inside the system boundary, with the include relationship and the note in place. The surrounding Markdown — the `## Checkout use cases` heading, any tables, any code samples — renders in the same pane, so the requirement, its diagram and its examples arrive as one document. ## What happens to diagrams you already published[​](#what-happens-to-diagrams-you-already-published "Direct link to What happens to diagrams you already published") Nothing breaks. This matters enough to be precise: * **Existing Mermaid source keeps working unchanged.** You do not need to rewrite a single diagram. * **Flowchart, state and class diagrams may lay out slightly differently**, because Mermaid 12 uses a new default layout engine and refreshed styling. A diagram can end up looking better with no code change — but if you had fine-tuned a layout by nudging shapes, the new engine may not reproduce it exactly. * **Nothing is a stored image**, so there is no migration to run. The source is the document; re-render and you get the new look. If a diagram does come out differently, pin the old appearance by overriding the theme in the fence, or re-check the ones with hand-tuned geometry first — those are the only pages worth reviewing after the upgrade. ## When a dedicated diagram app is the better choice[​](#when-a-dedicated-diagram-app-is-the-better-choice "Direct link to When a dedicated diagram app is the better choice") Pasting Markdown is the right default for standard diagram types because the diagram arrives with the document that explains it. Reach for a dedicated Mermaid macro instead when you want: * **One-click templates** for every diagram type, so nobody starts from a blank fence * **Themes, custom colours and fonts** to match your brand * **An AI agent that works on the page** — draft a diagram from a sentence, revise it in place, or convert code blocks already on the page into rendered diagrams * **A diagram-only workflow** when the page has no Markdown to preserve Our [draw.io vs Mermaid in Confluence comparison](/blog/mermaid-vs-drawio-confluence.md) covers the text-native versus visual-editor trade-off in full, and [Confluence diagram tools compared](/blog/confluence-diagram-tools-comparison.md) maps Mermaid, Excalidraw and Graphviz to the job each does well. ## Frequently asked questions[​](#frequently-asked-questions "Direct link to Frequently asked questions") ### Why do Mermaid diagrams not render when I paste Markdown into Confluence?[​](#why-do-mermaid-diagrams-not-render-when-i-paste-markdown-into-confluence "Direct link to Why do Mermaid diagrams not render when I paste Markdown into Confluence?") Because Confluence's editor is WYSIWYG and has no Mermaid renderer, so a `mermaid` fence is imported as a plain code block and stays dead text. Paste into a Markdown macro that renders Mermaid instead — Enhanced Markdown for Confluence runs Mermaid 12, so flowcharts, sequence, class, state, ER, Gantt, pie, journey and the new UML use case diagrams all render in the live preview. ### What does Mermaid 12 add for pasted documentation?[​](#what-does-mermaid-12-add-for-pasted-documentation "Direct link to What does Mermaid 12 add for pasted documentation?") UML use case diagrams through the `usecase-beta` keyword — actors, `systemBoundary` blocks, `include`/`extend` relationships and notes — which is exactly the type requirements documents kept losing in the paste. Mermaid 12 also refreshes the default layout and colour palettes for flowchart, state and class diagrams, and ZenUML fences gain conditionals, loops, parallel blocks and `try/catch`. ### Will my existing diagrams break after the Mermaid 12 upgrade?[​](#will-my-existing-diagrams-break-after-the-mermaid-12-upgrade "Direct link to Will my existing diagrams break after the Mermaid 12 upgrade?") No. Existing Mermaid source keeps working unchanged. Flowchart, state and class diagrams may lay out slightly differently because Mermaid 12 uses a new default layout engine and refreshed styling, so a diagram can look better with no code change. Nothing needs rewriting, and because nothing is stored as an image there is no migration to run. ### Should I paste a whole Markdown file or convert it once?[​](#should-i-paste-a-whole-markdown-file-or-convert-it-once "Direct link to Should I paste a whole Markdown file or convert it once?") Paste it into the macro. That keeps the Markdown as re-editable source on the page, so you update a diagram by editing a line instead of re-importing the file. A one-time conversion makes more sense only when non-technical editors will maintain the page afterwards, since they get the WYSIWYG view instead of the source. ### Is a dedicated diagram app better than pasting Mermaid in Markdown?[​](#is-a-dedicated-diagram-app-better-than-pasting-mermaid-in-markdown "Direct link to Is a dedicated diagram app better than pasting Mermaid in Markdown?") For standard types, pasting is faster and brings the math and code blocks in the same document. A dedicated Mermaid macro wins when you want one-click templates per diagram type, themes and custom colours, or an AI agent that drafts and revises diagrams in place on the page. *** *Render every Mermaid 12 diagram type inside a Markdown document with [Enhanced Markdown for Confluence](https://marketplace.atlassian.com/apps/1237026/enhanced-markdown-for-confluence/) — free for up to 10 users.* Try Mermaid Plus Diagrams & AI Agent for Confluence All 30 Mermaid diagram types plus a Rovo AI agent, with live preview and one-click templates — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=mermaid-plus-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [markdown](/blog/tags/markdown.md) * [mermaid](/blog/tags/mermaid.md) * [mermaid-12](/blog/tags/mermaid-12.md) * [usecase-diagram](/blog/tags/usecase-diagram.md) * [how-to](/blog/tags/how-to.md) * [developer-tools](/blog/tags/developer-tools.md)