Importing files into diagrams

PlantUML allows importing files into diagrams, enabling creation of reusable diagrams and themes.

PlantUML Add-on supports several types of sources of includable files.

Public URL

The URL must be publicly accessible by the add-on. The add-on will attempt to access the resource by issuing an unauthenticated HTTP GET request. This can be a public GitHub URL or any other publicly accessible resource.

!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Component.puml

Private absolute GitHub URL

Using private GitHub repositories assumes the add-on has been given access to the users’ GitHub as explained in Connect with Github.

!include https://raw.githubusercontent.com/myusername/myrepo/main/icons/font-awesome/server.puml

The example is similar to the one above it, except in this case the URL is not publicly accessible.

The add-on will issue a HTTP GET request against it using a secured proxy which was previously authorized by the Confluence admin.

Private relative GitHub URL

It is possible to reference files in repositories using relative paths that work the as relative file system paths. Paths are relative to the diagram. The diagram must have been imported from a GitHub repository as explained in Using GitHub Diagrams.

!include ../icons/common.puml
!include ../icons/devicons/mysql.puml
!include ../icons/font-awesome/server.puml
!include ../icons/font-awesome-5/database.puml

The example above will include four additional files into the diagram. These files must reside in the same repository as the diagram.

The example above is complemented with a directory structure below, showing locations of files relative to the diagram called my fancy plantuml diagram.puml.

.
├── examples
│   ├── complex-example.puml
│   ├── overload-example.puml
│   ├── my fancy plantuml diagram.puml
│   └── styling-example.puml
├── icons
│   ├── common.puml
│   ├── devicons
│   ├── devicons2
│   ├── font-awesome
│   ├── font-awesome-5
│   ├── font-awesome-6
│   ├── govicons
│   ├── material
│   └── weather
├── lib
│   └── icons
├── ride
│   └── theme.puml
└── src
├── assets
└── lib

PlantUML allows creation of constants which can be used to simplify imports like on the example below.

!define ICONS ../icons
!include ICONS/common.puml
!include ICONS/devicons/mysql.puml
!include ICONS/font-awesome/server.puml
!include ICONS/font-awesome-5/database.puml

Including Confluence-hosted files

The add-on also allows for including files hosted on the Confluence. The format is defined in the example below. The user must have at least View Page permissions. Three possible cases are shown below.

!include space-key:page-title^attachment.ext
!include page-title^attachment.ext
!include attachment.ext

Omitting the space key will assume the current space and omitting the page title will assume the current page.