Configure the template library to use custom template diagrams 07 Feb 2024


If you are using outside of Confluence, you can now customise the template library via the configuration using the templateFile property. Add your own custom templates, and specify which shape libraries and custom shape libraries are opened whenever a new diagram is created from a template.
You can configure to use a custom template library with your own diagram templates and custom shape libraries

When you work with a custom template library configuration, you can insert custom templates (without opening the relevant shape libraries), or create a new diagram to open the defined shape libraries.
You can configure to use a custom template library with your own diagram templates and custom shape libraries

Configure to use a custom template library file

Saved your custom template library file in a publicly accessible location, such as on GitHub, then add it to the configuration.

  1. Select … > Settings > Configuration or Extras > Configuration if you are using Classic mode.
  2. Add the templateFile property to the configuration, and click Apply.
    Configure to use a custom template library
  3. Click OK and then reload the browser tab to make the editor use the new configuration.
  4. Select … > File > New to open your configured custom template library.

Follow the instructions below to create your own custom template library file.

Create a custom template library file

The template library file is an XML file following a specific file format to define the template diagrams that are available in the template library dialog, as well as any custom shape libraries they open when a new diagram is created from a template.

Template library file format

<?xml version="1.0"?>
  <clibs name="example">
  <template section="Title" subsection="Subtitle" url="" title="Diagram" name="Tooltip" preview="" libs="general;basic" clibs="example" tags="term1;term2" />

Note: To include the default templates, start with our template library file change the path to all of the templates to be the URLs of the raw files in the jgraph/drawio repository.

For example, the basic class diagram template basic/classes.xml needs to be:

Example custom template library

Let’s step through the template library format with an example that includes the rockpool infographic and custom shape library from an earlier post.

In the template library file, the custom shape libraries opened by the templates are defined first, followed by the template diagrams.

Step 1: Define the custom shape libraries

Custom shape library files must be stored in an accessible location, such as into a GitHub repository, and use the mxGraphLibrary file format.

We’ll use the freehand-rockpool-shapes.xml custom shape library from the jgraph/drawio-diagrams repository.
The custom shape library to be used in one of the template diagrams
Note: Make sure you click through to Raw in GitHub to copy the library file’s URL.

Define the custom shape library or libraries in the template file using the <clibs> tag (you can have more than one of these).

  • Use a unique name="..." for each custom shape library category.
  • A category can contain multiple custom shape library sub-categories. Enclose the URL of each custom shape library file in an <add> tag, and precede the URL with a U.

Example: Define the freehand rockpool shapes custom library in the template library.

<clibs name="freehand">

Step 2: Define the template diagrams

Add a new <template> tag inside the surrounding <templates> tag and list the templates in the library.

These attributes are required for each template.

  • Add the section="..." name to place your template in a category.
  • Add the url="..." of the diagram file that is your custom template.
  • Add a title="..." to describe the diagram.

The following attributes are optional.

  • Add a subsection="..." if you want to place the template in a sub-category.
  • Add a name="..." to show a descriptive tooltip when you hover over the template preview.
  • Add a preview="..." URL for a .png image of the diagram to display via the magnifying glass preview function.
  • Add tags="..." as a semi-colon separated list.

Example: Add the rockpool infographic from the drawio-diagrams repository as a custom template:

  <template section="Infographics" 

Step 3: Open shape libraries by default

You can configure shape libraries to open automatically in the shapes panel whenever you create a new diagram from a template in

Built-in shape library: Add the libs="..." attribute inside a template definition as a semi-colon delimited list of the build-in shape libraries in

Custom shape library: Add the clibs="..." attribute to the <template> tag as a semi-colon delimited list of either the names you have defined in the <clibs> tags at the start of this file, and/or the encoded URLs to custom shape library files.

Example: The rockpool infographic template opens the freehand shapes custom library defined at the start of the template library file, and the built-in infographic shape library.

  <template section="Infographics" 

Customised template library file

We’ll also include two of the original basic templates - Class and Flow diagrams. The customised template library file now looks as follows:
Search for a custom template library to find templates with a matching title or tag

Custom template library in for Confluence Cloud for Confluence Cloud uses the Configuration space in your instance to organise and share custom templates.

See how administrators can set up and manage these custom template diagrams.

Search for a custom template

You can search for template diagrams using their tags and titles. For example, searching for freehand will return the rockpool infographic custom template.
Search for a custom template library to find templates with a matching title or tag

Follow us on GitHub, Twitter, Facebook.