Paste Mermaid Diagrams into Confluence — Now on Mermaid 12
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 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.
- Why Mermaid dies on the way into Confluence, and where the fix lives
- The paste workflow: repo Markdown in, rendered diagrams out
- What Mermaid 12 changes — use case diagrams, refreshed layout, richer ZenUML
- 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.