By linking to or embedding an existing draw.io diagram, you can display one diagram in a number of different locations in Confluence. Whenever you make changes to the master diagram, they are updated everywhere. This is much better than having multiple copies of a diagram in your Confluence instance, which are easy to get out of sync when changes are made.

You can also embed draw.io diagrams that are stored on Google Drive or OneDrive into your Confluence Cloud pages.

Single-source diagrams in Confluence

Confluence helps you avoid duplicating text with several built-in macros – they let you define a sentence, paragraph or section of a page as the master version with the excerpt macro, and then reuse that text elsewhere with the excerpt include macro. Having a “single source of truth” makes it quicker and easier to update reused content when changes are needed.

This is how complex software documentation is commonly developed and maintained. For example, keyboard shortcuts can be embedded in appropriate how-to pages in the online help very easily. It’s also useful for policies, prices or other information that is required in a number of locations in documentation stored in Confluence.

The same can be done with draw.io diagrams in both Confluence Cloud and Confluence Server. For example, a single master version of a flowchart, a BPMN diagram, or a floor plan can be used in multiple locations: in a reference library of documentation, on-boarding documentation, departmental help pages, etc.

As macros work differently in Server and Cloud, the steps you need to follow to embed an existing draw.io diagram are slightly different.

How to embed an existing draw.io diagram in Confluence Cloud

  1. Edit the Confluence page on which you want to embed your diagram, then type /draw to insert a macro. Select Embed draw.io diagram.
  2. Choose the diagram you wish to embed – recently updated diagrams are shown by default. If you don’t see your diagram here, click on Search and search for the name of your diagram. You can hover over a diagram to see its file name. Select the diagram you want to embed, then click Select.Search for and select the diagram you want to embed
  3. A preview appears so you can be sure it’s the right diagram. Click Insert to add it to your Confluence page.Insert the embedded diagram from the preview

You won’t be able to edit the diagram from the Confluence page when you have used the Embed draw.io diagram macro, but you will be able to add comments to it, just like on the original diagram.

To edit the diagram, find the page that has the original diagram and edit it, or go to the list of draw.io diagrams in that space and edit it directly.

How to embed a diagram stored on Google Drive or OneDrive

If you are using Google Drive or One Drive as the location for your draw.io diagrams, you can embed them in Confluence Cloud in much the same way. The instructions and screenshots below are for Google Drive, but OneDrive works similarly.

  1. Edit the Confluence page on which you want to embed your diagram, then type /draw to insert a macro. Select Embed draw.io diagram.
  2. Click the Google Drive or OneDrive tab. If you haven’t allowed draw.io to access your files on your cloud platform, click the blue Authorize button, and follow the prompts to allow access.
  3. When you return to the file picker, click Choose.
    Choose a diagram to embed from Google Drive
  4. Find and click on diagram file you want to embed, then click on the blue Select button.
    Find and select the diagram file in Google Drive that you want to embed
  5. Check the preview to make sure you have the right diagram, then click Select.
    Preview the diagram you want to embed from Google Drive
  6. Finally, click Insert to embed your diagram file from Google Drive into your Confluence Cloud page.
    Click Insert to embed the file you selected from Google Drive

How to embed an existing draw.io diagram in Confluence Server

  1. Edit the Confluence page on which you want to embed your diagram, then type {draw and select Drawio to insert the draw.io diagram macro.
  2. Choose the diagram you wish to embed – recently updated diagrams are shown by default. You can search for another diagram – select Search and search for the file name of your diagram. Select the diagram you want to embed, then click Link to diagram.
    Note: You can’t embed a draw.io template diagram or any diagrams you have configured as custom template diagrams.
  3. Optionally, edit the draw.io macro settings and filter your diagram – select the pages and layers that you want to display. Then publish your Confluence page.

Viewers will not be able to edit the embedded diagram when they hover over it – the edit button in the toolbar is greyed out.