Does Confluence render Mermaid diagrams? The app options, and the two reasons AWS diagrams break

Does Confluence support Mermaid diagrams natively?

No. Confluence has no built-in Mermaid macro, no code-block renderer that recognises the mermaid language, and no setting to enable one. A fenced block is displayed as source.

This puts Confluence in the same category as Bitbucket — the other Atlassian product with no native Mermaid — and behind GitHub and GitLab, which both render it in markdown without any add-on. For a company whose whole pitch is engineering documentation, it is a conspicuous gap, and it has been raised on the Atlassian community forums repeatedly.

The practical consequence: every Mermaid diagram in Confluence depends on a third-party app staying installed, licensed, and maintained. That is a different risk profile from an image, and it is worth deciding deliberately rather than by default.

Which Confluence Mermaid apps are available?

More than ten as of early 2026. The ones you will actually shortlist:

Read those "supported diagram types" lists carefully, because they are informative in a way the vendors did not intend. They enumerate flowchart, sequence, class, Gantt, ER, state, mindmap, timeline — the classic set. Architecture diagrams are not on any of them. That absence is your first signal that cloud architecture is not what these apps were built for.

Do the apps work on Cloud, Server, and Data Center?

Mostly Cloud, and that matters if you are self-hosted.

The Marketplace has skewed heavily toward Confluence Cloud, and several Mermaid apps — including the official Mermaid Chart app — are Cloud-only. Data Center teams have a meaningfully smaller catalogue to choose from, with Mermaid Integration for Confluence among the options that covers Cloud, Server, and Data Center alike.

If you are on Data Center, check hosting support before you evaluate features. It is the constraint that eliminates most of the list.

Why do AWS architecture diagrams break even with an app installed?

Because two different things have to be true, and most Confluence apps only satisfy one of them.

Requirement 1 is about age. The architecture-beta diagram type was introduced in Mermaid 11.1.0. An app bundling an older build has never heard of the keyword, so it reports a syntax error on a diagram that is perfectly valid. This is a hard failure and it is entirely a function of how recently the app updated its dependency.

Requirement 2 is about icon packs. Mermaid ships five built-in shapes — cloud, database, disk, internet, server. Everything else comes from an icon pack that the host application registers through registerIconPacks() at initialisation. That is a JavaScript call in the host's own code, not a setting a macro exposes. No Confluence app does it.

So even on a fully current app, a diagram full of aws: slugs lays out correctly and draws nothing inside the boxes.

How do you tell which failure you are hitting?

Look at the page. The two failures look completely different, and the diagnosis takes seconds.

Row three is where most teams land, and it is the one with no configuration answer. The layout is right, the connections are right, the labels are right, and every icon is a blank rectangle. Nothing you change in Confluence fixes it, because the missing piece lives in the app's build.

A quick way to isolate it: paste a trivial flowchart (graph TD; A-->B;) into the same macro. If that renders, the app works and your problem is specific to architecture-beta — version or icons, per the table above.

How do you publish an AWS architecture diagram in Confluence?

Export it and attach it. This is the route that works on Cloud and Data Center, on every app or none, today and after the next Marketplace reshuffle.

Author and validate the diagram first. This is the reference architecture from our validation guide — every placement and every edge holds up:

architecture-beta
service users(aws:res-users-light)[Users]
service internet(aws:res-internet-alt1-light)[Internet]
group account(aws:aws-account)[AWS Account]
group region(aws:region)[us-east-1] in account
service s3(aws:arch-amazon-simple-storage-service)[Assets S3] in region
group vpc(aws:virtual-private-cloud-vpc)[VPC] in region
service igw(aws:res-amazon-vpc-internet-gateway)[Internet Gateway] in vpc
service alb(aws:res-elastic-load-balancing-application-load-balancer)[Load Balancer] in vpc
group pub(aws:public-subnet)[Public Subnet] in vpc
service nat(aws:res-amazon-vpc-nat-gateway)[NAT Gateway] in pub
group priv(aws:private-subnet)[Private Subnet] in vpc
service app(aws:arch-amazon-ec2)[App Server] in priv
group data(aws:private-subnet)[Data Subnet] in vpc
service db(aws:arch-amazon-rds)[RDS Database] in data
users:R --> L:internet
internet:R --> L:igw
igw:B --> T:alb
alb:B --> T:app
app:R --> L:db
app:B --> T:nat
nat:R --> T:igw
app:L --> R:s3

Then, on the Confluence page:

• Export PNG from the editor.
• Insert it with Confluence's normal image tool.
• Attach the .mmd source file to the same page.
• Put the attachment name in a caption under the image so the next editor can find it.

That third step is what separates this from a screenshot. An image alone is a dead end — the next person to change the architecture has to rebuild the diagram from scratch. An image plus its source is a document someone can maintain.

Should you export PNG or SVG for Confluence?

PNG. Confluence handles it most predictably across the editor, the published page, PDF and Word exports, and the mobile app.

SVG can work, but its behaviour varies with how it is attached and which renderer the export path uses, and the failure is silent — the image simply does not appear. Unless you specifically need the diagram to scale for print, PNG removes a category of problem for no practical loss. (This is the same conclusion we reached for Bitbucket, for different underlying reasons.)

Should you install an app at all?

Yes, if your team writes a lot of core Mermaid — sequence diagrams for API flows, ER diagrams for schemas, state charts. That is a genuine quality-of-life win, several apps have free tiers, and reading those diagrams in the browser beats maintaining images.

No, if the goal is cloud architecture documentation. No app renders the icons, so you would be paying and taking on a dependency for something that does not solve your problem.

Most teams end up doing both: an app for the everyday diagrams, exported images for architecture. The important thing is knowing which category a diagram falls into before you file a ticket about the app being broken.

How does Confluence compare with other platforms?

The pattern across every platform we have tested is identical, and it is worth seeing side by side.

Every one of them renders core Mermaid to some degree. Not one registers a cloud icon pack. That is not six separate platform problems — it is one architectural fact about how Mermaid handles icons, showing up in six places.

Which is why the portable answer never changes: author and validate where the icon packs already live, export, and commit the source next to the image. If you are still writing the diagram, start with how to draw AWS architecture diagrams in Mermaid, and check the result against the common AWS architecture mistakes before you publish it to a page the whole company reads.