Why Confluence Cloud turns your SVG into a flat image
It is a deliberate security decision, not a bug or a missing setting. Here is what happens to the file, what you lose, and which of the workarounds people recommend actually exist in Cloud.
Short answer. An SVG file is not only a picture: it can carry links, scripts and references to outside resources. Rendering one live inside a page would let an attachment run code on your site, so Confluence Cloud converts it to a raster image before it is displayed. The picture survives. Everything interactive inside it does not, and there is no administrator setting that turns this behaviour off.
What actually happens to the file
You attach architecture.svg to a page and insert it. Confluence stores your original attachment untouched — you can still download exactly what you uploaded — but the version rendered on the page is a flattened image. That is why the diagram often looks slightly softer than in your editor, and why clicking a box does nothing.
People usually discover this at the worst moment: after building a navigation map for the documentation, where every service box was supposed to open its own page.
Why Atlassian does it this way
SVG is an XML format, and the specification allows a file to contain <script> elements, event handlers such as onclick, external references and embedded objects. A diagram that somebody downloaded from the internet and attached to a page is, technically, executable content uploaded by a user.
If Confluence rendered it inline, that content would run inside your site's origin, with your session. That is textbook cross-site scripting: a malicious attachment could read the page, act as the logged-in user, or quietly send data elsewhere. Rasterising the file removes the entire class of problem in one step.
This is worth repeating to your security team, because it usually decides the argument: the flattening is not Atlassian being lazy. It is the reason your wiki does not execute files that colleagues upload.
What you lose, precisely
| In the original file | After Confluence renders it |
|---|---|
| Hyperlinks on shapes | Gone. Clicking does nothing. |
| Hover states and tooltips | Gone. |
| Scripts and animation | Removed. |
| Selectable, searchable text | Becomes pixels. Confluence search cannot see it. |
| Crisp scaling | Fixed resolution. Zooming softens the image. |
| The picture itself | Intact. |
Careful with advice written for the wrong Confluence
Search for this problem and you will find answers recommending the HTML macro, or a custom user macro. Both belong to Confluence Data Center and Server. Confluence Cloud has no native HTML macro at all — that is an architectural difference, not something an administrator can enable.
Many of those threads were written between 2017 and 2021, when Server was the common deployment. If you are on Cloud, the advice does not apply, and following it will cost you an afternoon before you discover why.
What works without buying anything
Draw the diagram in a diagramming app instead of importing SVG
Tools that render diagrams natively inside Confluence keep links on shapes, because they are not attachments being displayed — they are diagrams being drawn by an app that Confluence trusts. draw.io is the usual choice and is free for small teams. If your diagram does not exist yet, this is the cheapest correct answer, and you should take it.
The catch is redrawing. If the map already exists as an SVG exported from Figma, Illustrator, Inkscape or Visio, and it is a hundred boxes across four layers, "just redraw it" is a week of somebody's life.
Put the links beside the picture, not inside it
Unglamorous but honest: insert the image, and under it keep a table of the same items with links. It survives forever, needs no app, and works on mobile. It is worse to use — nobody reads a legend of forty rows — but for a diagram of six boxes it is genuinely enough.
Split one big map into several smaller pages
If the diagram exists mainly to help people navigate, the navigation can live in Confluence itself: a parent page per area, child pages per service, and a small image on each. You lose the single overview, and you gain something that stays correct when the team reorganises.
When free stops being enough
Three situations, in the order we see them:
What an app can do that the platform will not
The reason a Marketplace app is allowed to render what Confluence refuses to is that it does not hand your file to the browser as-is. A well-built app parses the SVG, removes scripts, event handlers and external references, and renders only what is left. The dangerous class of content never reaches the page — which is exactly the guarantee Confluence itself was protecting.
The second thing an app can do is store a link as a reference to the page rather than as a URL. Then renaming the page, or moving it to another space, does not break the diagram, because the address is resolved fresh every time the page is opened.
Disclosure: I build one of these apps, Clickable SVG. It runs entirely on Atlassian infrastructure under the Runs on Atlassian programme, so diagrams are read and rendered inside your own site and nothing is sent to us. It strips the unsafe parts of the file and tells you what it removed rather than dropping things silently. There is a demo you can click through without installing anything, and the documentation is public.
If your case is one where the free routes above work, take the free route. This page is more useful to me as an honest answer than as an advertisement.
Frequently asked
Can I at least keep the text searchable?
Not in the rendered image. A common workaround is to paste the key labels into the page below the diagram, where Confluence search can index them.
Does the same happen in Confluence Data Center?
Data Center has the HTML macro and user macros, so an administrator can allow inline rendering. Most security teams keep those disabled for the same reason Cloud does not offer them.
Will Atlassian change this?
There are long-standing suggestions asking for native interactive SVG. Given the security model, expect the answer to keep being an app rather than a platform feature.
What about Mermaid and PlantUML?
Those are source text rendered into a diagram, not files being displayed, so the security problem is different. Several free renderers exist; some are no longer maintained, which is a separate trap — we wrote about the abandoned Mermaid apps and the same question for PlantUML.