app logo

Improved Attachments

A Confluence cloud app

Try it free

Keep your attachments in synch across different Confluences spaces and pages

Embed and reference existing attachments from different spaces, enabling a proper version management and utilize the power of additional display types.



Reference Files

Update attachments across multiple spaces from a single location


Display As Link

Embed attachments directly into paragraphs as download link


Upload from URL

Upload attachments directly from the web via an URL. Data urls are supported


Custom Macros

Gain full control with the custom macro editor. File upload, referencing and copying with just a few clicks.


Smart Macros

Display attachments differently depending on the file type


Quick Copy

Quickly copy attachments from one space to another

The issue Improved Attachment is solving

Step up your editing experience and add missing functionality to the new Confluence fabric editor. When editing a page, users are not able to include / link to files and images uploaded to other pages.

Instead, the file has to be attached a second time breaking the workflow and any chance for proper version management. Upon revision, the updated version has to be individually uploaded to all affected places leading to an uphill battle to keep your content up to date and organized.

Besides version management, Users often desire to add attachments to a page as download links or upload files directly from the web.

Example - Onboarding Page

The advantage of using Improved Attachment can be shown with the following use case.

The company logo is an integral part of the corporate identity and used over and over again in different spaces. A new onboarding page is automatically created for every new employee.

Using the custom macro the logo is only uploaded once to a single space. If a new version of the logo is created, only one file has to be replaced and the new version will be displayed in possibly hundreds of different locations without any additional work.

Preview of a page

The Data-compliance link showcases the second use of the macro. With different display types attachments can now be included as hyperlinks directly into a page. Similar to the logo, if the attachment is updated at the source location the link will point to the new version.

A native Confluence look and feel can be achieved by using the card layout display type.

Upload and file handling

Improved Attachments reintroduces the ability to display attachments and images already uploaded to Confluence.

  • Reference attachments. A referenced attachment automatically displays the current version of the file across different spaces and pages
  • Display already uploaded attachments. No need to re-upload a file in order to add it to a page
  • Quick copy attachments from a different pages to the current page
  • Upload files directly from the web via URLs
Macro preview upload dialog with existing files

Display Types

To fully customize the experience, three different display types are offered:

Download link: Display an inline link which can be embedded into the flow of a text allowing the user download the attachment

Resulting macro output as download link. Like a normal text link on a webpage.

Card display: emulates the default confluence editors file preview

Resulting macro output as cards. Cards are all the same height and share a similar display no matter the file type.

Media display: Show a smart preview with functionality changing depending on the file type

Resulting macro output as media display. e.g. a video player or an image.

Getting Started


  1. Log into your Confluence instance as an adminThe Find new apps or Find new add-ons screen loads
  2. Click the admin dropdown and choose Add-ons
  3. Locate Improved Attachments
  4. Click Free trial to download and install the app
  5. You're all set! Click Close in the Installed and ready to go dialog.

Any issues installing or usage the app? If you have any feedback or feature request don't hesitate to contact contact us. We are always eager to hear from our customers.

Usage - Add your first attachment

The addon was created with the goal in mind to be intuitive to use. Previews and tooltips are provided to guide the user if necessary.

In order to use Improved Attachments:

  1. Navigate to a page in which you want to embed an attachment intoThe user has to have normal edit permissions to perform this action
  2. Click Edit
Navigate to edit page mode by clicking the pencil icon on a confluence page
  1. Insert the macro by typing /improved The macro can also be accessed via the general macro editor.
  2. Choose either the Inline or the Block macro
Select one of the 2 shown macro options from the displayed popup.
  1. You're all set! The macro editor opens allowing you to choose a file.
Macro editor overview allowing to choose which file is displayed.

Inline vs Block Macro

Two distinct macros are available to the user. Block macros force a line break and allow you to align the content to the left right and center.

Inline macros do not break a line and can appear in the same row as text or other macros. These are useful if you want to display multiple items in a row e.g. multiple card macros or download links within a text.

Multiple macro outputs shown next to each other in a single line with the same height.

What is the difference between Referencing a file and creating a Copy. Single source of truth

When you choose to include an attachment from a different space you have the option to either Reference or Copy the attachment.

The copy command downloads the attachment and re-uploads it to the current page creating two distinct copies of the same file. The attachment will appear in the attachments list of this particular space. As these files are distinct copies changing one does not affect the other.

The reference option creates an internal link to the uploaded file. If the original file is changed at some point, the referenced file will also reflect those changes. Since Confluence is loading the file from the original page, user permissions still apply. If the source file is located in a restricted page, some users might not be able to view the attachment.

The attach existing file option is chosen inside the macro editor and the location of the referencing radio button group in the lower left is highligted

Reference option in the macro editor


Before opening a support ticket please check if you can find a solution for your problem in the FAQ section below. If you do not find an answer don't hesitate to contact us.

  • General questions

  • What does the file width option do? Why doesn't it work?

    When choosing the media display you have the option to specify a file width value in pixels. Here it is just enough to insert the raw number without any suffix.

    The smart display resolves to use different macros behind the back depending on the file type of the attachment. The file width is the preferred width the attachment will be displayed on the page. Some types (e.g.) image support specifying a width and some don't.

  • Provide additional edit options without the need to open the macro editor

    We would like to provide the possibility to directly edit the attachment display from within the editor page. This would result in a more smooth usage experience.

    For example the functionality to change the alignment of the file without needing to open the addon editor again. Sadly we are currently not able to provide these options due to Atlassian not supporting Macro-propertypanel-not-showing-in-the-new-editor additional customization on the new editor page.

    Once Atlassian decides to bring back the functionality documented here we are happy to release a new version update. The code is already written.

  • Feature X is missing. Replace the generic preview for filetype Y.

    We are interested in getting to know how you are using the app and are happy to improve the macro. This can only happen if we actually are aware of the request. Feel free to reach out to us so we can take a look at it and discuss your proposal.

  • Text wrapping and images

    One of the limitations of custom macros is text wrapping. Atlassian only provides us the ability to either create a block or an inline macro. Even if specified inline macros only line break the current line they are on. Thus, text wrapping simply is not possible due to the way Confluence implements and loads macros.

  • Loading Performance

    Improved Attachment does not store any actual files on our servers. The attachments are directly served from Atlassian's storage. Our app only provides light weight html and javascript files required to display the data.

    We consistently monitor our server performance and scale up resources if required. The servers are located in Germany. If you feel like the page loading takes too long due to our service please reach out to us. We are happy to take a look at it.

    If Germany as a server location should not be sufficient please let us know and we might set up a secondary geo location if enough interest is present.

  • Security

  • Connect Security Requirements Scan

    Marketplace apps have to comply with security standards. Please see the test report generated by Atlassians security labs.

  • Security Self Assesment

    We applied for and sucessfully completed the Security Self Assesment Program by Atlassian. The checks target data backup strategies, deyployment, information policy, access control and disaster recovery plans. Read more here:

  • What information is stored by your application? Jurisdiction of data.

    Improved Attachment only stores the absolute necessary information in order for the app to work. Please refer to our EULA for more information how your data is handled.

    Improved Attachment does not access or look at any user created content or attachments. Attached files may be proxied via our server to display the content. This is required due to limitations in the Confluence media api and CORS issues. The information is not stored or logged in any way or form.

    Our servers are hosted in a german data center with no external party having access to the infrastructure.

    If you have any question please feel free to reach out to us.

  • Backups

    A backup of our database is performed regularly in order to prevent data loss. These backups contain meta information about app installations as well as license keys and are saved at an off site location.

    The infrastructure are secured in a best practices manner and only accessible by employees of Brachtendorf Apps. Only the absolute minimum confluence Permissions are requested in order for this application to work.