Moving PlantUML diagrams from Confluence Data Center to Cloud

If your team keeps its architecture diagrams in Confluence as PlantUML, a Data Center to Cloud migration raises an uncomfortable question: what happens to all of them? The short answer is that the macros don't survive the trip, but the diagrams can — because with PlantUML, the diagram was never really the picture. It was always the text.

This walkthrough covers what actually breaks, what's recoverable, and a sequence that gets every diagram rendering again on the other side.

Why the macros break

Confluence Cloud and Confluence Data Center run entirely different app platforms. Data Center apps are server-side plugins installed into your own Confluence instance; Cloud apps are built on Atlassian's Forge or Connect platforms and run in Atlassian's infrastructure. A PlantUML plugin you installed on Data Center simply does not exist on Cloud — there is no Cloud version of the same binary, and the Confluence Cloud Migration Assistant can't invent one.

When the migration assistant moves a page containing a third-party macro that has no Cloud counterpart (or whose vendor hasn't provided a migration path), the macro typically shows up on the Cloud side as an "unknown macro" placeholder. The page migrates; the diagram stops rendering.

The good news: the source is the artifact

This is where PlantUML differs from drag-and-drop diagram tools. A PlantUML diagram is a block of plain text, like this:

@startuml
actor User
participant "Confluence Cloud" as CC
participant "PlantUML server" as PS

User -> CC : view page
CC -> PS : encoded diagram source
PS --> CC : rendered SVG
CC --> User : diagram
@enduml

Fig 01 · PlantUML source — the Cloud render path

Everything needed to reproduce the picture is in that block. If you can recover the text, you can re-render the diagram anywhere — a different macro, a different app, a different renderer. Nothing about your investment in the diagrams themselves is locked to the Data Center plugin that displayed them.

How recoverable the text is depends on how your Data Center plugin stored it. Most PlantUML macros keep the source in the macro body, which travels with the page content during migration — even when the macro itself renders as unknown, the source text is usually still inside it. Verify this on a few pages before you migrate rather than assuming it.

A migration sequence that works

1. Inventory before you migrate

On Data Center, use the macro usage view (or a CQL search against the macro name) to list every page that contains a PlantUML macro. This is the checklist for the whole exercise — after migration you want to be able to say "all 143 diagrams render," not "I think we got most of them."

2. Confirm the source survives

Run a test migration of one space containing diagrams, and open a migrated page in Cloud. Edit the unknown-macro placeholder and check whether the PlantUML source text is present inside it. If it is, your re-rendering work is editing macros, not reconstructing diagrams. If it isn't, export the sources from Data Center first, while you still have it.

3. Choose a Cloud renderer

On Cloud you need an app that renders PlantUML, and the main decision is where the rendering happens. PlantUML rendering requires a PlantUML server; Cloud apps generally either bundle a hosted renderer or let you point at one. Two things to weigh:

• The public plantuml.com server is free and zero-setup, but the diagram source is encoded into the request URL sent to it. For public or low-sensitivity diagrams that's fine; for confidential architecture, it may not pass your security review.
• A self-hosted PlantUML server (the official server ships as a Docker image) keeps diagram source inside your network. Apps that support bring-your-own-server let you use Cloud Confluence without routing diagram content through a third party's renderer.

4. Re-create the macros

With the renderer chosen, work through the inventory: open each migrated page, replace the placeholder with the new app's macro, and paste in the source. It's mechanical, and because the source is plain text it can be scripted against the Confluence Cloud REST API if the volume justifies it.

5. Verify against the inventory

Check the rendered output page by page against your step-1 list. Diagrams that used server-side !include directives or custom skin parameters are the ones most likely to need touch-ups, since those depend on files and configuration that lived on the old server.

The honest caveat

There is no fully automatic path. No migration tool currently transforms a Data Center PlantUML macro into a working Cloud macro end-to-end — the re-creation step is real work, proportional to how many diagrams you have. And if your old plugin stored rendered images as attachments while discarding the source, recovery means redrawing, not pasting. That's exactly why the inventory and the test migration come first: you want to know which situation you're in while the Data Center instance is still running, not after it's been decommissioned.

Budget the macro re-creation as part of the migration project, not as cleanup afterward. Teams that treat broken diagrams as a post-migration nice-to-have tend to discover which diagrams actually mattered at the worst possible moment.