Attachments Macro

This macro is available in Confluence Server and Data Center. Learn about the macros available in Confluence Cloud.

Add an Attachments macro to your page to display a list of files attached to your current page, or another page in your site. 

This macro is great for providing quick access to:

  • project files
  • forms and downloadable templates
  • images and diagrams.

Because you can display files attached to any page, you can use this macro to avoid duplication if you need to provide quick access to the same file on multiple pages.

On this page:

Related pages:

Screenshot: The Attachments macro, showing details of an attachment.

Screenshot of the attachments macro in a page. It's showing 5 attached files. The details are expanded for one file.

Once added to a page, people with appropriate space permissions can:

  • view a list of attached files
  • upload a file to the page, directly from the list 
  • edit attachment properties and labels
  • delete an attached file (this deletes all versions of the file)
  • preview image files
  • download all files attached to the page as a zip file. 

For general information about working with files in Confluence, see Files.

Add this macro to your page

To add the Attachments macro to a page:

  1. From the editor toolbar, choose Insert > Other Macros.
  2. Choose Attachments from the Confluence content category.
  3. Set any parameters. These are all optional. 
  4. Choose Insert

You can then publish your page to see the macro in action. 

Screenshot: Entering parameters and changing the sort order in the Blog Posts macro.

Change the macro parameters

Macro parameters are used to change the behaviour of a macro.

To change the macro parameters:

  1. In the editor, click the macro placeholder and choose Edit.
  2. Update the parameters as required then choose Insert.

Here's a list of the parameters available in this macro. 

Parameter

Default

Description

Filename Patterns
(patterns)

all

A comma-separated list of regular expressions, used to filter the attachments by file name. Note that the parameter values must be regular expressions. For example:

  • To match a file suffix of 'jpg', use .*jpg (not *.jpg).
  • To match file names ending in 'jpg' or 'png', use .*jpg,.*png

Attachment Labels
(labels)
(none)A list of labels, used to filter the attachments to display. If you wish to enter more than one label, separate the labels with commas. Confluence will show only attachments that have all the labels specified. (The match is an AND, not an OR.) For information on labelling the attachments, see Add, Remove and Search for Labels.

Include Old Attachment Versions
(old)

false

A value of true will include previous attachment versions in the list.

Sort By
(sortBy) 

date

The sort order for attachments. Note that people viewing the page can change the sort order by clicking the column headings. Valid values are:

  • date – sorts by updated date in reverse chronological order (newest first)
  • size – sorts largest to smallest
  • name – sorts alphabetically
  • created date - sorts by creation date in reverse chronological order (newest first)
Sort Order
(sortOrder) 
ascendingUsed in combination with the Sort By parameter, to sort the attachments in ascending or descending order.

Allow Upload
(upload) 

true

If selected, the list of attachments will include options allowing users to browse for, and attach, new files.

Page Title
(page) 
(none)Used to display attachments from another page. If you do not enter a page title, the macro will display the files attached to the current page.
Show Previews
(preview) 
true

Used to display a preview of the attached file. If true, preview will be visible when the list item is expanded.

It can be useful to disable previews if you have very large attachments. 

Where the parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro browser, it will be listed below in brackets (example).

Edit a file displayed by this macro

There are a few ways to edit attachments in Confluence. 

To edit a file from the attachments macro list:

  1. Click the arrow next to the file name to view its version history.
  2. Click Edit.
  3. Atlassian Companion will open the file in your desktop application.
  4. Make your changes and then save your file. When you're ready, click Upload in Companion to send the file back to Confluence.

Learn more about editing files in Confluence.

Other ways to add this macro

Add this macro as you type

Type followed by the start of the macro name, to see a list of macros. 

Add this macro using wiki markup

This is useful when you want to add a macro outside the editor, for example as custom content in the sidebar, header or footer of a space.

Macro name: attachments

Macro body: None.

{attachments:old=false|patterns=.*png,.*jpg|sortby=name|page=My page about chocolate|sortorder=descending|labels=chocolate,cookies|upload=false|preview=false}

Last modified on Feb 21, 2023

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.