Guides / PlantUML

How to add PlantUML diagrams to Confluence Cloud

Confluence Cloud cannot draw PlantUML by itself, and many PlantUML setups send the diagram text to a PlantUML server to turn it into a picture. SourceDocs runs PlantUML inside the reader's browser instead: no server to host, nothing to allow-list, and the diagram text never leaves Atlassian.

Write a diagram in the page · C4, AWS, Azure and Kubernetes icons · !include from Git · Show .puml files from Git · Diagram types and layout · Questions

Write a diagram in the page

Install SourceDocs for Confluence from the Atlassian Marketplace. A Confluence admin does this once for the site.
Edit a page and type /plantuml. Pick SourceDocs: Diagram (Mermaid / PlantUML).
Switch the language to PlantUML and type on the left. The preview on the right updates as you type. Insert example gives you a starting point for common diagram types.
Press Ctrl+Enter (or click Save) and publish the page.

@startuml
actor User
participant "Web app" as Web
participant "Auth service" as Auth
User -> Web: Sign in
Web -> Auth: Check password
Auth --> Web: Token
Web --> User: Dashboard
@enduml

@startuml and @enduml are optional; SourceDocs adds them when they are missing. Errors show PlantUML's own message with the line number, and the editor keeps the last drawing that worked until you fix it.

C4, AWS, Azure and Kubernetes icons

PlantUML's standard library works with the usual <...> includes, so architecture diagrams copied from documentation or from other tools draw without changes. C4 model:

@startuml
!include <C4/C4_Container>
Person(user, "Customer")
System_Boundary(shop, "Web shop") {
  Container(web, "Web app", "React")
  Container(api, "Orders API", "Go")
  ContainerDb(db, "Orders DB", "PostgreSQL")
}
Rel(user, web, "Uses", "HTTPS")
Rel(web, api, "Calls", "JSON")
Rel(api, db, "Reads and writes")
@enduml

AWS icons (the same pattern works for Azure, Kubernetes, tupadr3 font icons and the other standard libraries):

@startuml
!include <awslib/AWSCommon>
!include <awslib/Compute/Lambda>
!include <awslib/Database/DynamoDB>
Lambda(fn, "Order handler", "Node.js")
DynamoDB(table, "Orders", "On-demand")
fn --> table
@enduml

Libraries that set a path with !define or a !$variable and then include from it, as the Azure and Kubernetes icon sets often do in their examples, work too. We tested 45 real C4, AWS, Azure and Kubernetes diagrams from public repositories, and all of them render.

!include from Git

Shared styles and building blocks can live in a repository:

Any file link SourceDocs understands: !include https://github.com/org/repo/blob/main/uml/styles.puml, GitLab, Bitbucket and Azure DevOps links, and your own GitLab or GitHub Enterprise server once an admin has added it.
Paths relative to the diagram file when the diagram itself comes from Git: !include common/styles.puml.
Private repositories: includes are fetched with the token an admin stored for that provider.

Show .puml files from Git

Open the file in GitHub, GitLab, Bitbucket Cloud or Azure DevOps and copy the address from the browser bar.
In Confluence, type /git and pick SourceDocs: File from Git. Paste the link and click Preview.
Save. The page shows the diagram from the branch or tag in the link and picks up changes within 10 minutes. Refresh fetches it immediately.

Files ending in .puml, .plantuml, .iuml or .wsd, and any text file starting with @startuml, are drawn as diagrams. Markdown files with ```plantuml or ```puml blocks show the diagrams in place.

Diagram types and layout

SourceDocs runs PlantUML 1.2026.8: sequence, class, component, deployment, use case, activity, state, mind map, WBS, Gantt, JSON and YAML, Salt wireframes, C4 and more.

Without a server, there is no Graphviz. Diagrams that normally need it (class, component, deployment, use case, state and C4) use PlantUML's built-in layout engine, Smetana, instead. Results are clean, but very large diagrams can be arranged differently than on a Graphviz-based PlantUML server. Sequence, activity, Gantt, mind map and WBS diagrams never use Graphviz, so they look the same everywhere.

Questions

Is any PlantUML text sent to plantuml.com or another server?

No. PlantUML is part of the app and runs in the reader's browser. Standard library includes are fetched from the official PlantUML standard library repositories on GitHub, through Atlassian's Forge platform like any other public file. See the security page.

How do I move diagrams from another PlantUML app?

PlantUML sources are plain text. Copy the source from the old macro's editor into the SourceDocs editor. Old macros keep working while you switch page by page. If you have many pages, write to [email protected] and we will help plan the switch.

Can readers download the diagram?

Yes, as SVG or PNG from the toolbar above the diagram. Full screen opens the diagram fitted to the window, and PDF export contains it as a vector picture.

What does it cost?

Free for Confluence sites with up to 10 users. Above that, from 0.45 USD per user per month, with a 30-day free trial on the Marketplace.

SourceDocs for Confluence renders PlantUML, Mermaid, Markdown, OpenAPI and code files from GitHub, GitLab, Bitbucket and Azure DevOps. The Marketplace listing is in review. Read the documentation or write to [email protected].

More guides: Mermaid in Confluence · Files from GitHub and GitLab in Confluence · Markdown in Confluence · OpenAPI in Confluence