Confluence: Best Practices for Handling draw.io diagrams

I share here a couple of tipps, best practices I've came up while using draw.io with Confluence.

#1. Download the Desktop Client / Work offline

If you edit your draw.io diagrams in Confluence itself and regularly save your work, you will come up with a lot of versions in the background/ attachment history: this takes some storage space, and also it becomes hard to find back important versions from in-between edits.

I recommend editing the diagrams with the draw.io desktop client or app, save regularly offline, and copy-paste then the final version in the Confluence editor. (Ctrl+A/ Ctrl+C in the desktop app and Ctrl+A Delete and Ctrl+V in Confluence draw.io)

You can download the desktop client from diagrams.net here or the app from the Microsoft Store.

#2. Linking to anchors

See draw.io documentation here: https://drawio-app.com/using-anchors-within-draw-io-in-confluence/

Anchor in the same page

This is a cool feature in the Confluence Draw.io Add-On: you can comfortably link an element of a draw.io diagram to an anchor in the same Confluence page.

(Ctrl+K does not work, unfortunately.) Right-Click on the element and select Edit Link... in the context menu (or use the hotkey Alt+Shift+L).

Then under Page Content you can select the anchors or headings in the page you want to link to.

This creates a link of the type: #{pageTitle}-anchorname. This link is robust to a renaming of the page.

Anchor in another page

If you want to link to an anchor in another page, you will have to provide the full anchor URL which has a weird structure like:

http://myconfluence.com/display/spacekey/pagename#pagename-anchorname

See https://confluence.atlassian.com/conf76/anchors-1018768661.html#Anchors-Step2

The weird stuff about such links is that you have to type the pagename as prefix to the anchor name.

If you rename the page, the targeted links will be broken.

(The trick with {pageTitle} does not work if you aren't already viewing this page i.e. from another page.)

#3. Open Multiple Diagrams (Trap)

(TLDR; File->New not File->Open)

This is a bit counterintuitive. While having one diagram opened I wanted to open a second one and tried naturally File->Open (Ctrl+O).

This will close the first diagram/ replace it with the second one.

You need to use File->New (Ctrl+N): here you will be asked if you want to open an existing one.

And then you can

#4 Copy diagram to PowerPoint

To copy your draw.io diagram to PowerPoint, you can use the Draw.io add-in: it will allow you to browse for the Draw.io local file and convert the draw.io file to an image to be inserted in PowerPoint. I prefer to go to the Confluence page attachments, there you will find for each Draw.io diagram a corresponding image file that you can copy/ paste to PowerPoint directly. Click on the attachment image file to open it and right click->Copy image. This avoid the conversion step with the Add-In and is a bit faster. (This makes also in fact this Add-In useless.)

Thierry Dalon's Blog

December 3, 2021