Guides / Mermaid

How to add Mermaid diagrams to Confluence Cloud

Confluence Cloud has no built-in Mermaid support: a mermaid code block stays plain text. With SourceDocs you can write the diagram in the page with a live preview, or keep it in Git and show the file on the page, always current.

Write a diagram in the page · Show a diagram from Git · Large diagrams · Reading and exporting · Supported diagram types · Questions

Write a diagram in the page

Install SourceDocs for Confluence from the Atlassian Marketplace. A Confluence admin does this once for the site.
Edit a page and type /mermaid. Pick SourceDocs: Diagram (Mermaid / PlantUML).
Keep Mermaid selected and type or paste the diagram on the left. The preview on the right updates as you type. Insert example gives you a starting point for each diagram type.
Press Ctrl+Enter (or click Save) and publish the page.

A first diagram to paste:

flowchart LR
  user([Customer]) --> web[Web app]
  web --> api[Orders API]
  api --> db[(Orders DB)]
  api -. events .-> queue[[Message queue]]
  queue --> mail[Email service]

The editor has line numbers. If the source has a mistake, the preview shows Mermaid's own error message with the line number, and keeps the last drawing that worked, faded, until the error is fixed. You do not lose your picture while you type.

Show a diagram from Git

Many teams keep diagrams next to the code, so they are reviewed in pull requests like everything else. SourceDocs shows them in Confluence without copying:

Open the file in GitHub, GitLab, Bitbucket Cloud or Azure DevOps and copy the address from the browser bar.
In Confluence, type /git and pick SourceDocs: File from Git. Paste the link and click Preview.
Save. The page now shows the diagram from the branch or tag in the link and fetches the latest version at most every 10 minutes. Refresh on the page fetches it immediately.

Files ending in .mmd or .mermaid are drawn as diagrams. A Markdown file (a README or an architecture document) with ```mermaid blocks is shown as formatted text with the diagrams drawn in place, the same way GitHub shows it. Private repositories work after an admin adds a read-only token once; see private repositories.

Large diagrams

For flowcharts with dozens of nodes, Mermaid's ELK layout engine usually gives a cleaner result with fewer crossing lines. Add this block at the top of the diagram:

---
config:
  layout: elk
---
flowchart TB
  A --> B

On the page, wide diagrams are shrunk to the page width without being cut off. Small diagrams keep their natural size.

Reading and exporting

The toolbar above each diagram has zoom, full screen (opens fitted to the window), SVG and PNG download, and copy source.
"Match Confluence" follows the reader's light or dark mode. You can also pin one of Mermaid's themes.
PDF and Word export contain the diagram as a sharp vector picture, not a screenshot of the editor.

Supported diagram types

SourceDocs uses Mermaid 12.1 with the ELK layout engine. We test it against every example in the official Mermaid documentation, 547 diagrams in total. All of them render except the ZenUML ones, which need a separate Mermaid plugin. That covers:

Flowchart, sequence, class, state, entity relationship, user journey and Gantt.
Pie, quadrant, XY chart, Sankey, radar and treemap.
Requirement, git graph, C4, mind map, timeline, block, packet, kanban and architecture.
The newer types: Venn, Ishikawa (fishbone), Wardley map, railroad, swimlane, tree view, use case, Cynefin, event modeling and agent flow.

Questions

Is my diagram sent to a rendering server?

No. Mermaid runs in the reader's browser inside Confluence. There is no SourceDocs server. For files from Git, the only outbound request is the one from Atlassian's Forge platform to your Git provider. See the security page.

Can I move diagrams from another Mermaid app?

Yes. Mermaid sources are plain text: copy the source from the old macro's editor into the SourceDocs editor. Old macros keep working while you switch page by page.

Can I write Mermaid inside Markdown?

Yes. The SourceDocs: Markdown macro (type /markdown) draws ```mermaid blocks as diagrams, next to tables, task lists and code blocks.

What does it cost?

Free for Confluence sites with up to 10 users. Above that, from 0.45 USD per user per month, with a 30-day free trial on the Marketplace.

SourceDocs for Confluence renders Mermaid, PlantUML, Markdown, OpenAPI and code files from GitHub, GitLab, Bitbucket and Azure DevOps. The Marketplace listing is in review. Read the documentation or write to [email protected].

More guides: PlantUML in Confluence · Files from GitHub and GitLab in Confluence · Markdown in Confluence · OpenAPI in Confluence