Importing files into diagrams

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

PlantUML app supports several types of sources of includable files.

Public URL

The URL must be publicly accessible by the app. The app will attempt to access the resource by issuing an unauthenticated HTTPS 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 app has been given access to the users’ GitHub as explained in https://stratus-addons.atlassian.net/wiki/spaces/PDFC/pages/1733689350.

!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 app 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 https://stratus-addons.atlassian.net/wiki/spaces/PDFC/pages/1733787669.

!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 app 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.