Skip to main content

How to Use PlantUML in Confluence Cloud (3 Working Methods)

· 4 min read
NGPilot

Every team that migrated to Confluence Cloud with a wiki full of PlantUML diagrams hits the same wall: the macro they used on Data Center does not exist in Cloud, and there is no native PlantUML support to fall back on. The source text is usually still there, sitting in page storage — it just has nothing to render it.

Quick answer: there are three working methods in Confluence Cloud. Convert PlantUML into an editable Excalidraw whiteboard with an AI agent (best for diagrams you still maintain), render externally and embed an image (fine for frozen history), or write new diagrams in Mermaid (best for everything you have not created yet). This post shows all three.

Why there is no PlantUML in Confluence Cloud​

PlantUML rendering requires executing the PlantUML engine — a Java process that turns .puml source into SVG. On Data Center, apps bundled that engine server-side. Confluence Cloud's Forge platform does not give apps a Java runtime, so the classic PlantUML macros never made the jump, and Atlassian has no native diagram-as-code feature beyond Mermaid's text syntax in some app ecosystems. That is why searches for PlantUML in the Marketplace often return nothing useful for Cloud.

Method 1: convert PlantUML into an editable whiteboard​

Excalidraw Plus Whiteboards & AI Agent for Confluence ships with a Rovo AI agent that converts PlantUML source into an Excalidraw whiteboard. Open Confluence chat on your page and ask it to convert; the output is fully editable shapes on the canvas — reposition, restyle, and extend them like any drawn whiteboard.

This is the right method for live diagrams — the sequence diagram that changes with every sprint, the component diagram you actually keep updated. Two honest caveats:

  • Conversion is one-directional: PlantUML → Excalidraw. (Mermaid converts in both directions; PlantUML does not convert back.)
  • Exotic PlantUML constructs may need a touch-up after conversion. The shapes arrive; exotic styling sometimes does not.

Method 2: render externally, embed the picture​

For diagrams that are frozen history — the architecture as it was in 2023, the audit appendix — converting is wasted effort. Render the .puml outside Confluence:

  1. Paste the source into the public PlantUML server (plantuml.com/plantuml) or run it through a local plantuml.jar / CI render step.
  2. Export PNG (quick) or SVG (crisp at any zoom).
  3. Attach the image to the Confluence page.

Zero apps, zero cost, and the diagram looks exactly as it did on Data Center. The trade: it is a picture now. Nobody edits it in place, and search cannot read inside it. If a diagram needs its next revision, that is your signal to use Method 1 or 3 instead.

Method 3: write new diagrams in Mermaid​

For everything you have not written yet, the pragmatic answer is to stop accumulating PlantUML debt. Mermaid covers the everyday UML set — sequence, class, state, ER, activity-style flowcharts — and has first-class Confluence support: Mermaid Plus Diagrams & AI Agent for Confluence renders 30 Mermaid diagram types from a /mermaid macro with live preview, and its AI agent creates and edits diagrams from chat.

The syntax is different from PlantUML, but the mental model is identical: text in, diagram out, versioned with the page. The step-by-step Mermaid guide covers the move in ten minutes.

Which method for which diagram​

SituationMethodWhy
Live diagram you still edit1 — Convert to ExcalidrawEditable shapes on the canvas, AI edits in place
Frozen history / audit appendix2 — Render + embedZero effort, pixel-identical, nobody needs to edit it
New sequence/class/ER diagram3 — MermaidNative Confluence rendering, one syntax going forward
Diagram your team renders in CI2 — Render + embedKeep the pipeline; Confluence stays the display layer
Page migrated from Data Center1 or 2The source text survived; render or convert it before the page rots

Related guides