Guide · Confluence Cloud
How to add PlantUML diagrams to Confluence Cloud
You have PlantUML code: a sequence diagram from a design doc, a class diagram from a repository, or C4 code an AI assistant wrote for you. You want the diagram on a Confluence Cloud page. This page shows three ways, and where your diagram text goes with each one.
What Confluence Cloud does with PlantUML on its own
Confluence Cloud has no PlantUML support of its own. Pasted PlantUML stays text: put it in a code block and readers see the code, not the diagram. To see the diagram you need one of the options below.
First: where does your diagram text go?
PlantUML is a Java program. Most ways to draw it send your diagram text to a PlantUML server, which sends a picture back. The public server at plantuml.com even puts the (compressed) diagram text in the image address. For a diagram of your internal architecture, that matters: ask who runs the server and what it logs.
Option 1: render an image and upload it
Draw the diagram in a PlantUML editor (an IDE plugin, a local PlantUML install, or an online editor), download it as PNG or SVG, and upload the image to the page.
- It works today without installing anything in Confluence.
- The image goes stale. When the design changes, someone has to find the code, draw it again and replace the image.
- Online editors send your text to their server. A local install or IDE plugin does not.
If you go this way, put the PlantUML code in a code block (or an expand) under the image, so the next person can redraw it.
Option 2: a PlantUML macro that uses a PlantUML server
Several apps on the Atlassian Marketplace add a PlantUML macro. Many of them draw through a PlantUML server: the public one by default, or one your company runs. Check on the app's listing whether it uses a server, and which one.
- The code stays in the page, so the diagram stays editable.
- Your diagram text goes to that server each time the diagram is drawn. Running your own server keeps it inside your company, but someone has to host and update it.
Option 3: a macro that draws in the browser
Full disclosure: Dortus makes PlantUML Editor for Confluence. It is not on the Atlassian Marketplace yet. What it does:
- No PlantUML server. The PlantUML engine is inside the app and draws the diagram in the browser of the person viewing the page. The app does not connect to the internet.
- Code and preview side by side. The preview redraws while you type. An error marks the line.
- C4 built in. The C4-PlantUML library is included (see below).
- 12 examples to start from: sequence, use case, class, activity, component, state, deployment, ER, C4 context, C4 container, Gantt and mind map.
- On the page: zoom, open large, download SVG or PNG. Light and dark theme follow Confluence.
A few other PlantUML apps on the Marketplace also draw in the browser. Points worth comparing: the editor (a preview while you type, errors on the right line), C4 support, and what happens on PDF export.
One limit of drawing without a server: includes from a web address (!include https://...) are refused, because the app does not fetch anything from the internet. Paste the included code into the diagram instead.
C4 diagrams
C4-PlantUML adds context, container and component diagrams to PlantUML. Most examples on the web start with an include from GitHub:
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
PlantUML also ships the same library inside its standard library. Write the include with angle brackets and nothing is fetched:
@startuml
!include <C4/C4_Container>
Person(customer, "Customer")
System_Boundary(shop, "Online shop") {
Container(web, "Web app", "React")
Container(api, "API", "Node.js")
ContainerDb(db, "Database", "PostgreSQL")
}
Rel(customer, web, "Uses")
Rel(web, api, "Calls", "JSON")
Rel(api, db, "Reads and writes")
@enduml
That form works on a PlantUML server and in PlantUML Editor for Confluence alike.
Asking an AI assistant for PlantUML
ChatGPT and Claude can write PlantUML. Describe the system in plain words, name the diagram type, and ask for the code only. Two things that save time:
- Ask for the standard library include for C4 (
!include <C4/C4_Container>), not the GitHub address. - Paste the error back. If PlantUML reports an error on a line, give that line and the message to the assistant and ask for a corrected version.
Which option fits
One diagram that will never change: an image, with the code saved under it. Diagrams people keep editing, and a PlantUML server you trust: a server-based macro. Diagrams people keep editing, and no server at all: a macro that draws in the browser.
Questions
Spotted something wrong on this page, or an option we missed? Email support@dortus.com.