Reading Time: 9 min

The first part of our training course covers the basics of using draw.io in Confluence (Cloud, Server, or Data Center): adding a diagram to page and editing existing diagrams.

Of course, to do this you’ll need to know how to add blank and template diagrams to a Confluence page and change how they’re displayed when someone views your page.

Task 1: Insert a diagram

Insert a new diagram in Confluence Cloud

  1. To insert the draw.io macro when editing a Confluence page, type /draw, and select draw.io Diagram.
  2. In the template manager, the Basic template section and a Blank Diagram are selected by default.
  3. Enter a name for the diagram and click on Create (or double-click on Blank Diagram).
  4. Insert a random shape from the General shape library on the left-hand side of the editor.
  5. Click Save & Exit.
  6. Save the Confluence page.
Add a new diagram to your Confluence Cloud page

Insert an existing diagram in Confluence Cloud

If you’ve already created draw.io diagrams, you can always use these existing files and adapt them after copying them.

  1. Type /draw and select the macro Embed draw.io diagram to look for an existing diagram to embed.
  2. Now you’ll see a screen where you can either:
    • Choose from one of the recent diagrams
    • Search for existing content
    • Embed existing diagrams from Google Drive or OneDrive
    • Upload files or embed a diagram from a URL
    • Import a diagram via CSV
  3. Click on the diagram of your choice and click Select.
Add an existing diagram to your Confluence Cloud page

Insert a new diagram in Confluence Data Center/Server

  1. To insert the draw.io macro when editing a Confluence page, type {draw and select draw.io Diagram (or select + from the toolbar and click draw.io Diagram).
  2. In the template manager, go to draw.io Diagram at the top left (if another diagram type was selected).
  3. Click on Blank and select Create (or double-click on Blank Diagram).
  4. Insert a random shape from the General shape library on the left-hand side of the editor.
  5. Click Save & Exit.
  6. Enter a name for the diagram.
  7. Save the Confluence page.
Add a new draw.io diagram to your Confluence Server page

Insert an existing diagram in Confluence Data Center/Server

  1. Insert the macro as in the previous step.
  2. In the template manager, go to draw.io Diagram at the top left (if another diagram type was selected).
  3. Beneath the option Blank, there is a section of Recent diagrams. Select one of the recent diagrams or (if the diagram you are looking for wasn’t created recently), click on the option Search in the left toolbar and type in your search terms for the specific diagram.
  4. Click on the diagram. You’ll now see the following options: Link to Diagram and Copy.
    • The Copy option will copy the template, which you can then use and adapt to create a new diagram.
    • The Link to diagram option will create a diagram that will always be synced with the parent file. When you want to edit, it will then take you to the parent diagram.

You can also insert diagrams by simply dragging and dropping the existing draw.io xml file onto the drawing canvas. Drag and drop also works to import single Visio or Gliffy files in Confluence Cloud or Server/Data Center.

Add an existing diagram to your Confluence Server page

Task 2: Open and save a template diagram

If you want to quickly create a diagram for a specific use case, you can choose from a variety of predefined templates from our template libraries. draw.io includes many templates by default. This includes diagrams like flowcharts, mind maps, and more. You can find these templates in the various categories listed to the left of your workspace. Generating a clone of these templates is very easy.

Your task (for Confluence Cloud)

  1. Insert the draw.io macro when editing a Confluence page.
  2. Enter a name for the diagram.
  3. Select a template from the template manager in the left toolbar and click Create to open it (double-clicking is also fine).
  4. Click Publish.
  5. Click Save & Exit.
  6. Save the Confluence page.

Your task (for Confluence Data Center/Server)

  1. Insert the draw.io macro when editing a Confluence page.
  2. Select a template from the template manager in the left toolbar and click Create to open it (double-clicking works too).
  3. Click Save & Exit.
  4. Enter a name for the diagram.
  5. Save the Confluence page.

Please Note: Once you have given the diagram a name, you can’t change it.

Task 3: Change how the diagram appears on the Confluence page

You can change the appearance of a diagram when editing the Confluence page.

Confluence Cloud

In Confluence Cloud, the macro details can be handled either in Confluence page view mode or in the editor itself. On Confluence page view level, simply hover over the diagram and select the gear wheel to adapt the viewer settings. Here you can:

  • Activate the Simple Viewer (Note: If you activate this option, you will no longer have the option to access the diagram from Confluence page view mode. To uncheck the viewer, go to Confluence page edit mode, edit the diagram, and follow the procedure described below).
  • Deactivate the Lightbox feature in Confluence page view mode.
  • Change the position of the diagram to centered.
  • Choose a High Resolution Preview.
  • Change how the draw.io toolbar is displayed.
  • Decide if links in the diagram will open in a new or existing browser window.
  • Set the Zoom level.
  • Select which layer and page of the diagram should be visible per default in the Confluence viewer (only applies if your diagram has multiple layers and pages).
Change diagram settings in Confluence Cloud view mode

In Confluence edit mode, you can scale your diagram:

  • Center your diagram.
  • Adjust the scale of your diagram to be wider.
  • Set diagram to full page width.
Change diagram settings in Confluence Cloud edit mode

In draw.io edit mode you can access all of the options that you also find on the Confluence page view level. If you activated the simple viewer, you can only uncheck this option in the editor. Just click on your drawing canvas to make sure nothing is selected. In the right hand side, you’ll find the Format Panel. In the Diagram tab, you’ll see the Viewer Settings at the top.

Confluence Data Center/Server

When you click on a diagram in edit mode, a toolbar is displayed either above or below the diagram. You can use this toolbar to:

  • Duplicate the diagram.
  • Change the displayed size within the page (in the same way as images in Confluence).
  • Remove the diagram.
CHange diagram settings in Confluence Server edit mode

In addition, you can change the draw.io macro settings if you click on the Edit Macro button. Here you can:

  • Set a custom Width for your diagram.
  • Change how the draw.io toolbar is displayed.
  • Decide whether your diagram will be displayed with a grey border around it.
  • Deactivate the lightbox feature in Confluence page view mode.
  • Activate the simple viewer (draw.io toolbar will be invisible in Confluence view mode).
  • Decide if links in the diagram will open in a new or existing browser window.
  • Select which layer and page of the diagram should be visible per default in the Confluence viewer (only applies if your diagram has multiple layers and pages).
Edit macro settings in Confluence Server

Your task:

  • Edit the Confluence page.
  • Select the diagram, click on Edit Macro, and change the settings as follows: Width 600, Toolbar Embedded, Border inactive, Simple Viewer activated.

Tip: When viewing the Confluence page, you can change the zoom level as required.

That’s it for the first exercise in this self-directed training course. Keep an eye out for the next installment in this series where you’ll learn how to work with text and connectors, create a tree diagram from scratch, and work with the symbol library.

Tutorial exercise 2: Edit a diagram and change colors