Working with attachments and video in Confluence wiki

Atlassian’s Confluence is a nice wiki platform, but it can be confusing at times when working with attachments and video. Of course, as a wiki platform, the whole point is to have the content on wiki pages, but there are all sorts of circumstances when attachments are needed regardless.

In this post, I will detail some basic, and some advanced, lessons learned from using Confluence when it comes to attachments and video.

Attachments are stored on pages

If it helps, you can think of a Confluence page as a folder on a hard drive. The attachments are located on the pages, so all attachments on a single page have to have a unique name and there is no way to create further subdivision among attachments on a page.

You can drag-and-drop files to a page (you do not need to be in edit mode) to save them as attachments to that page. This way you can easily save multiple files at once. Combine this with a Gallery macro on a page and multiple image files to quickly create an album of images.

Advanced: You can create multiple Attachments macros on a page and have them display attachments based on file name patterns, labels, or location (so you can display attachments from multiple pages). The Browse button used for file upload on these macros gets slightly confusing, though, because you are not really uploading the content to the macro, but to the page, so the content you upload may not even be displayed by the macro.

There is basic version control

There is version control in Confluence, although it is very basic. Any file you upload to a page with the same file name as an existing attachment becomes a new revision of the attachment. Old revisions can be accessed from the attachments list (Tools – Attachments).

Because of this, you may need to rename attachment from time to time. You can rename an attachment from the Properties menu of that attachment from the attachments list. You can also move attachments from one page to another and add comments to attachments from the same menu.

Advanced: If you remove a page in Confluence, an administrator can return it. If you remove an attachment, it is gone for good. It is sometimes a good idea to not give all users the rights to remove attachments, but instead create a specific page, let’s call it Trash, where the users can move unneeded attachments. This page can then be periodically emptied.

You can display and work with Office files directly from Confluence

If your attachments are Office documents, you can place an Office Word/Excel/Powerpoint macro on a page to display the content directly on the page. On top of the content there will be an Edit in Office button which will launch the appropriate application to edit the document. When you save it, it is saved as a new revision of the attachment in Confluence. The same button is available in the attachments list if you choose not to display the content of the file on the page.

You can also import a Word document to Confluence as a page instead of an attachment (Tools – Import Word Document).

Advanced:  Importing a Word document function can be used to delete a page and all its child pages (which, ironically, cannot be done in any other way). Instructions on how to do that can be found here.

You can embed video from external sources or from attachments

Confluence has a rather good macro, Widget Connector, with which you can embed video from Youtube and Vimeo, among other things.

However, sometimes you just need to upload the video files locally. This is a not-so-good part of Confluence. The file size limit for attachments can be configured by the Confluence administrator: the default size is 10 MB (we use 24 MB to give a bit more options while still limiting the size – it can go up to gigabytes).

You can upload video files as attachments and display them on the page with the Multimedia macro. Unfortunately, the Multimedia macro has two major drawbacks: it often fails to recognize the resolution of the video (you need to configure it manually) and it loads the entire video file before you are able to play it.

Configure the Multimedia macro to be slightly taller than the video file to ensure that the play controls at the bottom are visible. For example, for a 1280×720 video, set the size of the Multimedia macro to 1280×740.

Because the video is loaded in its entirety before playing, make the video file as small as possible. My preferred tool to do this is Handbrake, and here are some very simple instructions on how to use it. I also prefer to resize the video to a bit smaller size, which can also be done with this software. As an example, I transcoded a Full HD (1920×1080) video taken with a tablet into 1280×720 resolution and MPEG-4 encoding without any other changes to quality, and it resulted in file size reduction from 166 MB to 12 MB. That’s pretty significant, I would say.


Confluence is not a content management system. However, in many use cases it is possible to live with the basic features it offers as long as you know a little bit about how it works. The methods detailed above are some of the things I get asked about the most, and knowledge of these simple methods usually helps.

Of course, if you really need to manage lots of file content, you need a content management system. However, the vast majority of content can really be handled as wiki pages once you have the mindset to do so, and the little that cannot, can usually be handled even with the basic tools offered by Confluence.

Photo: Atlassian party by Dmitry Baranovskiy @ Flickr (CC, cropped)


Author: Ville Kilkku

I run my own consultancy business, so if you find the ideas on this blog intriguing, contact me at or call me at +358 50 588 5043 and we can discuss how I can help you solve your business problems. I am currently based in Finland, but work globally.