PlantUML Confluence Integration: Complete Setup Guide (2026)

Setting up plantuml confluence integration lets your team embed live, version-controlled UML diagrams directly inside Confluence pages — no image uploads, no broken links, no out-of-date screenshots. Diagrams update automatically when the source code changes and are tracked in Confluence page history.

This guide covers the full plantuml confluence plugin setup for Cloud, Server, and Data Center, plus integration guides for GitHub, GitLab, Slack, WordPress, and Notion. Whether you are documenting microservices architecture or writing API specs, PlantUML integrates with every major platform your team uses.

For quick diagram generation before setting up any integration, our free PlantUML generator online lets you create and export diagrams in seconds — no install, no Java required. Use it alongside any of the integrations in this guide.

Why Use PlantUML Confluence Integration for Team Documentation?

The plantuml confluence integration solves the most common documentation problem: diagrams that go stale. When architecture diagrams live as uploaded image files, they quickly fall out of sync with the actual system. With PlantUML embedded directly in Confluence pages, the diagram source is part of the page — it rerenders whenever the page loads.

Confluence with PlantUML also enables version-controlled diagrams. Every edit to a diagram’s PlantUML code is tracked in Confluence page history, so you can compare how an architecture evolved over time alongside the text documentation that describes it.

PlantUML Confluence Plugin: Atlassian Marketplace Setup

The plantuml confluence plugin is available on the Atlassian Marketplace. Multiple vendors offer PlantUML plugins — the most widely used is PlantUML Diagrams for Confluence, which supports both Confluence Cloud and Data Center with a free tier for small teams.

• 1
  Open Confluence Settings

  Go to Settings → Apps → Find new apps (Confluence Cloud) or Settings → Manage add-ons → Find new apps (Server/DC). You need Confluence Admin permissions to install apps.

• 2
  Search for PlantUML

  Type PlantUML in the app search box. Look for PlantUML Diagrams for Confluence or Comala PlantUML. Check the reviews, install count, and whether it supports your Confluence edition (Cloud vs Server/DC).

• 3
  Install and Confirm

  Click Install. Confirm the permissions dialog. The plugin typically activates within 30 seconds — no Confluence restart is needed on Cloud; Server/DC editions may require a service restart depending on the plugin.

• 4
  Test on a Page

  Open any Confluence page in edit mode. Type /plantuml in the editor to invoke the macro. A code input box appears — paste any PlantUML syntax between @startuml and @enduml, then save the page to see the rendered diagram.

PlantUML Confluence Cloud vs Data Center vs Server

The plantuml confluence experience differs significantly between deployment types. Cloud users get managed plugin updates and simpler setup but less rendering control. Data Center and Server users can self-host a PlantUML rendering server for maximum performance, privacy, and offline support.

PlantUML Confluence Macros: Embedding and Editing Diagrams

Once the plantuml confluence plugin is installed, diagrams are embedded using a macro in the Confluence page editor. The macro wraps your PlantUML code and replaces it with a rendered image when the page is published. The source code is stored inside the page, not as a separate file.

Using the Macro in the Page Editor

@startuml
!theme cerulean

package "Microservices" {
  [User Service]
  [Order Service]
  [Payment Service]
}

database "Shared DB"

[User Service] --> "Shared DB"
[Order Service] --> "Shared DB"
[Order Service] --> [Payment Service]
@enduml

Most plantuml confluence plugins support the full skinparam property set, all 40+ built-in themes, and the !include directive for shared stylesheets — though !include from external URLs may be restricted in Cloud environments for security reasons.

Keyboard Shortcut for Macro Insertion

PlantUML GitHub Integration: README and Pull Request Diagrams

GitHub does not natively render PlantUML in markdown files — unlike Mermaid, which has been native since 2022. However, there are three reliable approaches to embed PlantUML diagrams in GitHub README files, pull requests, and wikis.

Option 1: plantuml.com Server URL (Simplest)

Encode your PlantUML code in the official URL format and embed it as a markdown image. No plugin or GitHub Actions required.

![Sequence Diagram](https://www.plantuml.com/plantuml/png/SoWkIImgAStDuNBAJrBGjLDmpCbCJbMmKiX8pSd9vt98pKi1IW80)


![Architecture](https://www.plantuml.com/plantuml/svg/SoWkIImgAStDuNBAJrBGjLDmpCbCJbMmKiX8pSd9vt98pKi1IW80)

Option 2: GitHub Browser Extension

The official PlantUML for GitHub browser extension renders PlantUML blocks fenced with backtick notation directly inside GitHub pages — including README files, issues, pull requests, and wikis. Available for Chrome and Firefox.

Option 3: GitHub Actions Auto-Export

Set up a GitHub Action that runs on every commit. The action installs PlantUML via Docker, generates PNG or SVG from all .puml files in your /docs/ folder, and commits exports back to the repository. For a detailed walkthrough, this developer guide on anoff.io covers the full GitHub Actions setup with PlantUML.

# .github/workflows/plantuml.yml
name: Generate PlantUML diagrams
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Generate diagrams
        uses: cloudbees/plantuml-github-action@master
        with:
          args: -tsvg docs/**/*.puml
      - name: Commit generated diagrams
        uses: EndBug/add-and-commit@v9
        with:
          message: "Auto-generate PlantUML diagrams"

GitLab Native PlantUML Support and Browser Extension

GitLab has native PlantUML support on self-hosted instances — no plugin needed. A GitLab administrator enables it in Admin settings by pointing to a PlantUML rendering server. Once enabled, any user can write fenced PlantUML code blocks in markdown files, wikis, merge request descriptions, and issue comments.

Enabling PlantUML in GitLab Admin Settings

```plantuml
@startuml
[Frontend] --> [API Gateway]
[API Gateway] --> [User Service]
[User Service] --> [Database]
@enduml
```

PlantUML Slack Integration: Diagram Sharing in Channels

The official PlantUML Slack integration allows team members to generate and share diagrams directly inside Slack channels without leaving the messaging interface. See the full list of PlantUML running options including Slack at plantuml.com/running.

Setting Up PlantUML in Slack

• Visit the PlantUML Slack integration page and click Add to Slack
• Grant the required permissions to the app
• In any channel, type /plantuml followed by your diagram code
• The app responds with a rendered PNG image posted inline in the channel thread

/plantuml
@startuml
Alice -> Bob : Feature request
Bob --> Alice : Confirmed for Sprint 3
@enduml

PlantUML Confluence vs WordPress Plugin and Notion Embeds

Beyond plantuml confluence, PlantUML integrates with several other content platforms. The WordPress and Notion options are simpler to configure but offer less native integration than the Confluence plugin ecosystem.

WordPress PlantUML Setup

Install the PlantUML Renderer plugin from the WordPress Plugin Directory. Once activated, wrap your diagram code in [plantuml]...[/plantuml] shortcodes in any post or page. The plugin renders diagrams via the plantuml.com server — no local Java install required.

Notion Embed (No Plugin Required)

Notion does not have an official PlantUML plugin. The workaround is to encode your diagram source into a plantuml.com PNG URL and insert it as an image block. While this works for static diagrams, the image does not update automatically when you change the diagram source — you must regenerate the URL manually.

PlantUML Confluence Best Practices for Technical Writing Teams

Getting the most from plantuml confluence requires a few workflow conventions. These practices keep diagrams consistent, maintainable, and easy for non-developers to understand and update over time.

• One diagram per Confluence macro. Avoid embedding multiple diagrams in a single macro block. Separate diagrams are independently editable and easier to review in page history.
• Always add a title to embedded diagrams. Use title My Architecture — v2.3 inside the PlantUML code so the rendered diagram is self-labelled even when viewed outside the page context.
• Apply a consistent theme. Add !theme cerulean (or your team’s chosen theme) to every diagram in the wiki. This creates a uniform look across all documentation pages without any manual styling.
• Link diagrams to related pages. Add a Confluence internal link below each embedded diagram pointing to the page that documents the components shown. This creates a navigable documentation graph.
• Use plantuml confluence for architecture decisions. Embed a component or C4 diagram alongside Architecture Decision Records (ADRs) to give the context that text alone cannot provide.
• Review diagram source in pull requests. If you use Confluence for a team that also uses Git, store the canonical .puml source file in your repository and import it into Confluence on each release cycle to keep both systems in sync.

URL Generator, Shareable Links and Offline Export Options

Every PlantUML diagram can be shared as a URL — no Confluence or GitHub account required. The plantuml.com server encodes your diagram source in the URL path, so anyone with the link can view or download the rendered PNG or SVG without any tools installed.

Building a Shareable URL

The URL format is: https://www.plantuml.com/plantuml/FORMAT/ENCODED_SOURCE

• Replace FORMAT with png, svg, pdf, or txt
• Replace ENCODED_SOURCE with your diagram code encoded in PlantUML’s deflate+base64 format
• Use the online encoder at plantuml.com, or any PlantUML editor including our free PlantUML generator, to get the encoded string automatically

Offline Export Without Java

To export PNG or SVG without Java, use VS Code in server mode or our browser-based generator. For batch CI/CD export, the official Docker image handles all diagram types without a local Java install.

See our PlantUML editor VSCode guide for export configuration, and our PlantUML cheat sheet for the full CLI flag reference.

Related Articles