Diagram as code in Confluence Cloud: a working setup

"Diagram as code" is the practice of writing diagrams as plain text and letting an engine draw them. Instead of dragging boxes, you write:

@startuml
package "Checkout service" {
  [API] --> [Payment worker]
  [Payment worker] --> [Ledger]
}
@enduml

and the renderer produces the picture. If that seems like a step backwards from a visual editor, this article is the case for why engineering teams keep choosing it — and the concrete setup for doing it inside Confluence Cloud, which supports the workflow well but not natively.

Why text beats pixels for long-lived diagrams

Every advantage of diagram-as-code follows from one property: the source of truth is text.

• Diffs. A change to a text diagram is a reviewable diff — you can see that the payment worker gained a queue, not just that "the image changed."
• Version control. Text lives happily in git, in page history, in code review. The diagram's history is real history, not a folder of architecture-v3-final.png.
• Regeneration. Renaming a component across nine diagrams is a find-and-replace, not nine re-drawing sessions. Diagrams can even be generated from code or config.
• Portability. The text renders anywhere the engine runs. Your investment is in the source, not in any one tool's file format.

It's worth noticing that this whole workflow grew up in open source and stays there: PlantUML, Mermaid, and Graphviz — the engines that define the category — are all open-source projects. That's not a coincidence. The workflow's premise is that your diagrams are plain text you own, processed by tooling you can read, run, and replace. A diagram-as-code setup built on a black box undermines its own point.

The Confluence Cloud gap

Confluence is where engineering documentation lives, but Confluence Cloud has no native diagram-as-code support — you add it with a Marketplace app. It's an active corner of the Marketplace: more than ten apps compete on rendering PlantUML, Mermaid, or both, and new ones were still launching as of mid-2026. Which is good news for the workflow's health and slightly bad news for choosing — so here are the axes that actually differentiate them:

1. Engine. PlantUML has the range for architecture work (C4, component, state, deployment); Mermaid travels lighter and matches what repo hosts render natively. Our comparison of the two in Confluence goes deeper.
2. Rendering path. Client-side rendering keeps diagram text in the page; server-side rendering sends it to a render server — whose operator you should get to choose. If diagrams describe internal systems, insist on bring-your-own-server.
3. Source storage. Diagram text stored in the macro body inside your page survives app switches and migrations; text stored app-side doesn't.
4. Openness. An open-source app makes points 2 and 3 checkable instead of promised — which, for a workflow whose entire ethos is inspectable text, is the consistent choice.

A working setup with PlantUML

The setup we build for, using Palori's free, source-available PlantUML for Confluence:

1. Install the app from the Atlassian Marketplace into your Confluence Cloud site.
2. Insert the PlantUML macro from the slash menu on any page, paste your diagram source, publish. The diagram renders as SVG inline; the source is stored in the macro body, inside the page.
3. Decide where rendering happens. Out of the box, the app uses the public plantuml.com renderer — zero setup. For sensitive diagrams, a site admin can point it at a private PlantUML server under Settings → Apps → PlantUML; the server is an open-source project with an official Docker image.
4. Treat diagram source like code, because now it is: keep canonical sources for important architecture diagrams alongside the systems they describe, review changes, and paste updates into the page like a deploy.

The honest caveat

Diagram-as-code has a learning curve and an aesthetic ceiling. Your first PlantUML sequence diagram will take longer than dragging four boxes would have, and a designer with a visual tool will always produce a prettier one-off. For a diagram you'll draw once, present once, and never touch again, a visual editor is genuinely the better tool. Text earns its keep where diagrams live — documentation that changes with the system it describes. That's most of what's in a good Confluence space, which is why the workflow fits here so well.