DEV Community: Mikhail Klimenko

"Diagrams in Confluence: draw.io, Mermaid, PlantUML or an attached SVG"

Mikhail Klimenko — Sun, 06 Sep 2026 03:21:20 +0000

The choice is usually made by whoever draws the first diagram, and then everybody lives with it for years. It is worth five minutes of thought, and the deciding question is not which tool is best but who will edit this thing next.

Short answer. A visual editor such as draw.io for diagrams that non-engineers maintain. Mermaid or PlantUML when the diagram belongs with the code and should be reviewed like code. An attached SVG when the picture comes from a design tool and you need it to look exactly right. A screenshot when the diagram will genuinely never change again.

The four options

A diagramming app inside Confluence

draw.io is the common choice, and it is free for small teams. The diagram is created and edited inside the page, links on shapes work, and anyone who can use a mouse can maintain it. This is the default answer for architecture maps, process flows and floor plans that live in the documentation and get corrected by whoever notices the mistake.

The cost is lock-in of a mild kind: the diagram lives in the app's format, and moving to something else later means exporting and redrawing.

Mermaid or PlantUML: diagrams as text

Here the diagram is source code — a few lines describing nodes and arrows, rendered into a picture. The appeal is real: text goes into version control, diffs are readable, and a diagram can be generated by a script from the system it describes.

Two things to know before choosing this. Confluence Cloud does not render Mermaid natively, so you need an app for it, and several of them exist including free ones. And the editing audience narrows sharply: a technical writer will not touch a diagram that has to be edited as syntax, so the diagram becomes the property of the engineers, whether you intended that or not.

An SVG made somewhere else

The diagram comes from Figma, Illustrator, Inkscape, Visio or an architecture tool, and lands on the page as an attachment. It looks exactly as designed, which is why people do it.

The catch is documented and unavoidable: Confluence Cloud flattens an attached SVG into a raster image before showing it, because SVG files can carry scripts. Links inside the diagram stop working, hover states disappear, and the text inside becomes pixels that search cannot see. We wrote about why this happens and what to do separately.

A screenshot

Unfashionable, and sometimes correct. For a diagram that documents a moment — an incident timeline, the state of a system before a migration — a picture is the honest format, because there is nothing to keep up to date.

It becomes a problem the moment the thing it shows starts changing. Then the source file is on somebody's laptop, that somebody has left, and the picture on the page is quietly wrong.

Side by side

	Visual editor	Mermaid / PlantUML	Attached SVG	Screenshot
Who can edit	Anyone	People comfortable with syntax	Whoever owns the source file	Nobody
Links on shapes	Work	Limited	Lost on display	None
Searchable text	Usually	Yes, the source is text	No, it becomes pixels	No
Review like code	No	Yes, that is the point	No	No
Looks exactly as designed	Close enough	The renderer decides	Yes	Yes
Needs an app	Yes	Yes	No, but interactivity needs one	No

How to actually choose

Ask three questions in this order, and the answer usually falls out.

Who edits it next year? If the honest answer is "a writer, a manager, whoever spots the error", pick a visual editor. Text-based diagrams look elegant right up to the moment a non-engineer has to change one box.

Does it change with the system? If the diagram describes something that evolves and can be generated from it, text wins. A picture of an architecture is out of date the week it is drawn; a generated one is not.

Do people need to click through it? A map that exists to help people navigate documentation is worth nothing if the boxes are not links. That rules out screenshots entirely, and it is the reason an attached SVG needs help.

One more thing worth checking before you commit: whether the app you are about to standardise on is still maintained. Several diagram apps for Confluence have been abandoned over the last few years, and their users found out the hard way. Our notes on the abandoned Mermaid apps and the same for PlantUML cover how to tell.

Disclosure: I build Clickable SVG, which covers the third case — an SVG that already exists and needs its links working inside Confluence, plus rendering for Mermaid and PlantUML source. If your diagram does not exist yet, draw it in a visual editor and you will not need my app at all. That is the honest recommendation and it costs me nothing to make.

Frequently asked

Can we mix approaches?

Most teams end up doing so, and that is fine as long as it is by decision rather than by accident. The failure mode is four approaches in one space because four people each picked their favourite.

What about diagrams generated from code?

That is the strongest case for the text-based route: the diagram is produced by the build, so it cannot drift from reality. Worth the syntax cost when the system changes weekly.

Does exporting to PDF keep the diagrams?

Rendered diagrams appear in exports as images. Interactive behaviour, including links, does not survive a PDF, which is a good reason not to make navigation depend on a document that people print.

What to check before installing a Confluence app

Mikhail Klimenko — Sun, 06 Sep 2026 03:14:16 +0000

Four questions decide almost everything: where your data goes, whether the vendor is still alive, what happens when you uninstall, and what the bill looks like when the team grows. Everything else is detail.

Short answer. Look for the Runs on Atlassian badge, which is a verified technical fact rather than a claim. Check the date of the latest version and whether the vendor answers reviews. Ask what uninstalling leaves behind. Then look at the price for the team size you will have next year, not the one you have today.

1. Where does the data go

This is the question your security team will ask, so it is worth being able to answer it before they do.

Apps on Atlassian Cloud are built on one of two platforms. Forge apps can run entirely inside Atlassian's own infrastructure. Connect apps run on the vendor's servers, which means your page content travels to a machine you know nothing about, in a country you may not have chosen.

Neither is automatically wrong. A vendor's server is not evil, and plenty of good apps use one because they genuinely need to. But it is a different conversation with your compliance people, and it should be a conscious decision rather than a surprise.

What the badges actually mean

Badge	What it tells you
Runs on Atlassian	The app uses only Atlassian-hosted compute and storage, matches the data residency of your product, and cannot send data outside your instance without your consent. Atlassian applies this automatically to eligible Forge apps, so nobody can simply claim it.
Cloud Fortified	About the vendor's practices rather than the architecture: service level objectives, incident process, a named support channel, a 24-hour response promise for critical issues, bug bounty participation. Being replaced by Atlassian Enterprise Certified, with onboarding from the third quarter of 2026 and Cloud Fortified phased out by the end of the year.
No badge	Not a verdict. Small vendors often skip programmes with fees and paperwork. It means you ask the questions yourself.

The practical difference: Runs on Atlassian answers "can this app leak my content", Cloud Fortified answers "will anyone pick up the phone at two in the morning". Enterprises usually need both. A ten-person team almost always needs only the first.

2. Is the vendor still there

Abandonment is the most common way an app hurts you, and it is quiet. Nothing breaks on the day the vendor stops caring — it breaks a year later, during a platform change, when nobody answers the ticket.

Three signals, in order of usefulness:

The date of the latest version. On the Marketplace listing, look at when the app was last updated. Two years of silence for an app on an evolving platform means somebody moved on.

Replies to reviews. Open the reviews tab and look for vendor responses, especially to the angry ones. A vendor who answers a one-star review in public is a vendor who will answer your email.

Whether it is still a Connect app. Connect apps cannot be updated after March 2026 and stop receiving fixes at the end of that year. An app still on Connect with no migration announcement is on a countdown, whatever its rating says.

3. What happens when you uninstall

Ask this before installing, not after. There are two very different answers.

Some apps only display what already exists in Confluence: a diagram that is an attachment on your page, a list built from your pages. Uninstalling removes the macro and leaves your content exactly as it was. The risk is a page that looks broken until somebody edits it, and nothing more.

Other apps store their own data — configurations, entities, records that live only inside the app. Uninstalling takes that with it. That can be fine, as long as you know it in advance and know what export you get. It is a bad thing to discover during a licence renewal argument.

4. The price at the size you will actually be

Marketplace pricing is tiered, and the tiers are not linear. An app that costs a few dollars a month for ten people can cost several hundred at a hundred and fifty. Open the pricing tab and look at the row for the team size you expect a year from now.

Also check the free tier. Most apps are free for teams up to ten users, which is genuinely free rather than a trial, and that is the cheapest way to judge an app: install it, use it for a month, and decide with evidence.

The questions worth sending the vendor

*Disclosure:* I build four Confluence apps, and all of them carry the Runs on Atlassian badge, which is precisely why I can write this section without discomfort: the answer to the first question is no, nothing leaves your site, and it is verified by Atlassian rather than promised by me. The apps are Clickable SVG, Smart Search, Table Export and Word Import, all free for teams up to ten.

Frequently asked

Does a high rating mean an app is safe?

It means people liked using it, which is a different question from where their data went. Ratings and trust badges answer different things, and the badge is the one your security review cares about.

Can I restrict what an app is allowed to do?

App permissions are declared by the app and shown at install time. Read that screen rather than clicking through it: an app asking for far more than its job needs is a signal in itself.

Our security team wants a review. What do we send them?

The Marketplace listing's security tab, the vendor's privacy statement, and the answer to the data egress question above. For a Runs on Atlassian app that is usually the whole review.

What if the app we already use gets abandoned?

Check what you are actually locked into. Apps that only render your own content leave nothing behind; apps holding their own data need an export before you switch. We wrote about the specific cases of SVG out and the Connect end of life.

How to get a Confluence table into Excel

Mikhail Klimenko — Sun, 06 Sep 2026 02:30:21 +0000

Short answer. Confluence exports whole pages to PDF and Word, but it has no built-in export for a single table. Select the table on the page, copy it, and paste into Excel: for a simple rectangular table that is the end of the story. Merged cells, long tables and multi-table pages are where it stops being that easy.

Route one: copy and paste

Click just above the top-left cell and drag to the bottom-right, or click into the table and select all of it, then copy. In Excel use Paste Special → Text rather than a plain paste: a normal paste brings Confluence's styling with it, and you spend the next ten minutes stripping background colours out of cells.

This is the right answer more often than app vendors like to admit. If you need one table today, do this and stop reading.

Where it breaks

Situation	What you get
Merged cells	Columns shift left in every row below the merge, and the file looks fine until somebody sums the wrong column.
Numbers with separators	Excel may read `1,250` as text, or as 1250 depending on locale. Check one cell before trusting the totals.
Dates	Converted according to the spreadsheet's locale, not yours. This is where day and month swap places silently.
Links inside cells	Usually arrive as display text, and the address is lost.
Very long tables	Fine technically, painful in practice: selecting three hundred rows in a browser is its own small ordeal.

The merged-cell problem is the one that costs money. A shifted column does not look like an error, it looks like data, and it goes into a report that somebody signs.

Route two: export the page to Word, then to Excel

From the page menu choose Export → Word, open the file, and copy the table from there. It sounds like a detour, and it is, but Word handles merged cells more predictably than the browser clipboard, and for a single complicated table it sometimes saves the day.

Not worth it for more than one or two tables: you are still copying by hand, only with an extra step.

Route three: the REST API

If somebody on the team is comfortable with scripting, page content can be pulled through the Confluence REST API and the tables parsed out of it. This is the only free route that scales to many pages.

Two warnings. The stored page is not what you see: a table produced by a macro is stored as the macro, not as rows, so your script will find nothing where the browser shows a neat table. And parsing merged cells correctly is exactly the same problem as above, now yours to solve in code.

When copying stops being reasonable

Same arithmetic as always. One table is two minutes. A page with six tables is fifteen. A quarterly report that pulls tables from forty pages is a day of somebody's life, every quarter, forever — and it is the kind of task that quietly gets skipped, after which the report is out of date.

The table is a source, not a picture. If people export the same table every month, the export is part of a process, and manual steps in a process fail on the month somebody is on holiday.
Many tables, one file. Collecting tables from a whole space into one workbook with a sheet per table is not something you do by hand twice.
Merged cells everywhere. Any export that does not expand merged cells produces a file that is subtly wrong, and subtly wrong is worse than obviously broken.

What a tool should do here

Three things, and they are not glamorous. Expand merged cells so every row has the same number of columns. Keep numbers and dates as numbers and dates rather than text. Collect several tables into one workbook instead of producing a folder of files nobody will merge afterwards.

Disclosure: I build Table Export for Confluence, which does exactly that: one table, a whole page, or every table in a space into a single workbook, with merged cells expanded so columns stay aligned. It runs inside Atlassian's infrastructure, so page content is read in your own site and nothing is sent to me. Free for teams up to ten people.

There are other apps in this category, and for a single table the free copy-paste beats all of them. Pick by what your case actually is.

Frequently asked

Can I schedule an export? Nothing built in will do that. If the export needs to happen on a schedule, you are looking at automation against the API, or at accepting that a person will click a button.

What about Google Sheets instead of Excel? Pasting into Sheets behaves much like Excel, with the same merged-cell trap. CSV imports cleanly if you produce a proper CSV in the first place.

Does exporting a table export its formatting? Colours and fonts are presentation, and any sane export drops them. What matters is that values, numbers and dates survive intact.

The table comes from a macro. Will it export? Copying from the browser works, because you are copying what is rendered. Scripts reading stored page content usually see the macro instead of the rows — worth checking before building anything on that route.

How to import Word documents into Confluence Cloud, and where the built-in import stops

Mikhail Klimenko — Sun, 06 Sep 2026 02:14:24 +0000

Short answer. Create a page, then next to the Share button open More actions → Templates and import → Import, choose Word document (.docx), and pick your file. No app required. One file becomes one page: headings, tables and images come across, drawn shapes do not.

The built-in import, step by step

Select Create in the top navigation to open a blank page.
Next to Share, open More actions, then Templates and import, then the Import tab.
Choose Word document (.docx) and select the file.
Read the result before publishing, and move the page to where it belongs in the tree.

Do this once with a real document from your archive before planning anything bigger. Five minutes here will tell you more about your migration than any estimate.

What survives, and what does not

In the Word file	After import
Heading styles (Heading 1, 2, 3)	Become Confluence headings, and the page gets a usable outline.
Text made large and bold by hand	Stays large and bold text. Not a heading, so it is invisible to the table of contents.
Simple rectangular tables	Come across intact.
Merged cells and nested tables	Usually survive, but check them: complex layouts are where import problems hide.
Images	Attached to the page and shown in place.
Shapes and drawing objects	Replaced with placeholders. This is documented behaviour, not a bug.
Text boxes, headers and footers	Do not come across in any useful form.
Tracked changes and comments	Do not come across. Accept or reject them in Word first.

Prepare the document, not the import

Almost every disappointing import is a document problem rather than a Confluence problem. Three habits fix most of it.

Use real heading styles. If your authors made headings by increasing the font size, Confluence has no way to know what is a heading. Applying Heading 1 and Heading 2 in Word before import is ten minutes that saves an hour of cleanup.

Flatten the drawings. Anything drawn with Word shapes — a process diagram, a boxed callout, an org chart — will arrive as a placeholder. Screenshot it, or export it as an image, and put the image in the document instead.

Clean the file. Accept tracked changes, delete comments, and remove the cover page if it exists only for the printed version. Confluence pages do not need cover pages, and everyone who imports one deletes it afterwards.

Where the built-in import stops

The import is genuinely good for what it is. It runs into three walls, and all three are the same wall: it was built for a document, not for an archive.

One file, one page. A 90-page regulation becomes a 90-page Confluence page. Nobody reads that, and nobody can link to a section of it. Splitting it into a tree by heading level is manual work.
One file at a time. Fine for five documents. For a hundred and fifty, it is a week of somebody clicking through the same four menus, and the week never gets scheduled.
No structure across documents. Each import lands where you happen to be. Turning a folder of files into a coherent space with parents and children is a separate job, done by hand.

This is why so many Confluence migrations stall halfway. The tooling handles the document in front of you and has nothing to say about the shared drive behind it.

When the archive is the problem

The honest test is arithmetic. Count your documents and multiply by fifteen minutes, which is a realistic figure once you include fixing headings and placing the page. Twenty documents is a morning. A hundred and fifty is four working days that nobody has, which is exactly why those files are still sitting on the shared drive two years after the decision to move.

Disclosure: I build Word Import for Confluence, which exists for that second case: drop a batch of files, get a page tree, with documents split by heading level rather than dumped as one long page. It reads the files inside your browser, so nothing is uploaded to a third party — which matters when the documents are regulations, contracts or HR policies. It is free for teams up to ten people.

If you have twenty documents and good heading styles, use the built-in import and keep your money. This post is here to help you tell which case you are in.

Frequently asked

Does the import work on mobile? Do it from a desktop browser. The import lives in the page creation menu, which is awkward on a phone, and you will want to check the result on a large screen anyway.

What about .doc files from the nineties? Open them in Word and save as .docx first. The old binary format is not accepted, and converting it also gives you a chance to fix the heading styles.

Can I import a PDF the same way? No. PDF is a layout format with no reliable structure inside, so any conversion is guesswork. If the PDF was generated from a Word file, find the original and import that instead.

We are moving from SharePoint. Same story? Mostly. The files are usually .docx underneath, so the same rules apply — with the extra step of deciding what not to bring. A migration is the one moment when deleting outdated documents is easy.

How to find the Confluence pages nobody maintains any more

Mikhail Klimenko — Sat, 05 Sep 2026 22:26:04 +0000

Short answer. Search inside a space and set the last modified filter to a cut-off date, for example before last year. For a sharper cut, the query space = KEY AND type = page AND lastModified < now("-365d") can be run through the Confluence REST API. Both give you a snapshot; keeping that list live on a page needs a macro from an app.

Why this piles up

Nobody sets out to abandon documentation. It happens because writing a page is somebody's job and retiring one is nobody's. The service gets decommissioned, the project ends, the tool is replaced — and the page stays, indexed and searchable, looking exactly as authoritative as the page next to it that is still true.

The damage is not storage. It is that a new engineer follows instructions for a system switched off two years ago, and an auditor finds a policy page dated 2023 that contradicts the current one.

What Confluence gives you out of the box

Search filters

The advanced search screen lets you narrow by space, by contributor, by label and by last modified date, including "before" a date you choose. For a first pass this is often enough: pick a space, set the date to two years ago, and look at what comes back.

CQL through the API

Confluence's query language is more precise than the filter UI, and in Cloud it is available through the REST API. A typical audit query looks like this:

space = ENG AND type = page AND lastModified < now("-365d") ORDER BY lastModified ASC

Add AND label = "policy" to narrow it, or AND creator = "someone" to find what left with a person who has moved on. This is the right tool if somebody on the team is comfortable calling an API and turning JSON into a spreadsheet.

Labels and page reports

If your spaces use labels consistently, the built-in macros that list content by label will assemble a page of everything tagged, say, runbook. That does not tell you what is stale, but it does tell you what should have been reviewed.

Where the built-in route runs out

Search results cannot live on a page. You can find the pages, but you cannot put the finding anywhere. Teams paste a snapshot into a page called "Documentation audit", and the snapshot is wrong within a month.
CQL is a skill, not a setting. The syntax is fine for an engineer and a wall for the technical writer or the office manager who actually owns the space.
An audit that needs rerunning does not get rerun. Anything requiring somebody to remember a quarterly chore will survive exactly two quarters.

An audit routine that survives contact with reality

The mistake is treating this as a one-off cleanup. Do it as a standing list instead.

1. Pick one space, not the whole site. A site-wide list of eight hundred pages gets closed and never reopened. One space with forty candidates gets dealt with.

2. Set the cut-off by content type, not by feel. Runbooks go stale in six months. Policies live for years. Onboarding material is wrong the moment the tooling changes. One cut-off for everything produces noise.

3. Sort oldest first. The bottom of that list is where the obvious corpses are — the page about the office printer on floor three, the setup guide for a laptop model nobody has.

4. Decide per page: update, archive, or delete. Most pages deserve archiving. Archiving removes a page from search and navigation while keeping it recoverable, which is what people usually mean when they say "delete it".

5. Leave the list in place. This is the step everyone skips. If the list stays on a page and rebuilds itself, next quarter's audit is ten minutes instead of an afternoon, because everything handled has already dropped off it.

Careful with one thing: "not edited" is not the same as "not used". A page can be correct and heavily read for three years without a single edit. Use the date to build a shortlist, then judge each page on what it says.

What to do with what you find

Archive rather than delete. The archived page keeps its history and can be restored, and it stops competing with the current page in search results — which was the real problem.

Give the survivors an owner. A page with a named owner and a review date is a page that gets updated. A page owned by "the team" is a page owned by nobody.

Write the retirement into the process. If your definition of done for decommissioning a service does not include "archive its documentation", this list will be exactly as long next year.

When an app is worth it

Apps in this category exist for one reason: to turn the snapshot into something that stays true. The condition sits on a page, the list rebuilds itself as pages change, and a page that somebody finally updated leaves the list on its own.

Disclosure: I build one of them, Smart Search. Conditions are picked from dropdowns rather than written in CQL, the app shows in plain English what the list will contain before you save it, and CQL is still there in manual mode if you prefer it. It runs entirely on Atlassian infrastructure, so your pages are read inside your own site and nothing is sent to me. There is a demo you can click through without installing anything.

If a quarterly search filter and a spreadsheet work for your team, use those. The audit matters more than the tooling.

Frequently asked

Can I see which pages nobody reads, rather than nobody edits? Views are a different signal from edits, and where page analytics are available on your plan they answer that question better than a date filter. The two lists rarely match: plenty of unread pages are perfectly correct, and some heavily read pages are dangerously out of date.

What is a reasonable cut-off? 180 days for operational material, one year for reference, two years before anything gets deleted rather than archived. Adjust once you have seen your first list.

Does this work across the whole site? Technically yes, practically no. Space by space is the only version that gets finished.

Why Confluence Cloud turns your SVG into a flat image

Mikhail Klimenko — Sat, 05 Sep 2026 21:54:25 +0000

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 I see them:

The diagram already exists as SVG. It came out of a design tool, an architecture tool, or a vendor. Redrawing it inside a diagram editor is not a fix, it is a project.
The diagram changes often. Someone updates the source file and re-attaches it. Any solution that requires manually rebuilding links after every update will be abandoned within two months.
The links must survive a reorganisation. Links written as page URLs break the moment a page is renamed or moved to another space, and nobody notices until a reader complains.

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 me. 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 post 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.