Back to blog

A simpler way to view attachments in Confluence

October 16, 2009 - Posted in Uncategorised Posted by:

Tags: , ,

…or how to display attachments in an unordered list.

Something that bugs me in Confluence is the way that attachments are shown. The default view is a big table with just about all the information related to each attachment.

This is great if you want all this detail, but I’m a simple soul with simple needs.

Krug suggested “Omit needless words”. In this case, it’s more of “Omit needless metadata”.

Less is more

Enter {list-attachments} – a user macro that dispenses with the excess. It displays an unordered list with the filename, file size and last modified date. If there’s a comment for the attachment, this is displayed in the link text rather than the filename.

This is a really straightforward view of the attachments on the page.

How do I install {list-attachments} ?

It’s pretty easy. As a Confluence administrator, go to Confluence Admin | User Macros and click on Create a User Macro.

Macro name: list-attachments


## MACRO: list-attachments 
## Updated: 2011-03-15
## View page attachments in a simple list
## USAGE: {list-attachments}

	#set ($attachmentsList = $content.getLatestVersionsOfAttachments())
    ##<div class="listAttachmentsDiv">
        #if ($attachmentsList.size() > 0)
		        #foreach( $attachment in $attachmentsList )
			        #set ($currentAttachmentId = $
					#if ($attachment.comment && $attachment.comment.trim().length() > 0)
						## Display the comment as the link text instead of the filename
						<li><a href="$generalUtil.htmlEncode("${req.contextPath}${attachment.downloadPathWithoutVersion}")">$generalUtil.htmlEncode($attachment.comment)</a></li>
						## Display the filename as the link text
						<li><a href="$generalUtil.htmlEncode("${req.contextPath}${attachment.downloadPathWithoutVersion}")">$generalUtil.htmlEncode($attachment.fileName)</a></li>

Accept the defaults for the other fields, then click on Save

To call the macro in the page type: {list-attachments}

The result:

Now you’re left with a simple list of links — much purer than a big fat table of metadata.

For extra points (Updated 2011-03-15)

If you’ve got a might great slab of files attached to the Confluence page, why not wrap this usermacro in the azList macro:


The result:

No Comments

Brad 4 years ago

Nice work, David. This could be a nice enhancement when you don’t want that huge block stretching across your full page.

My own worry about user macros is keeping them up to date with any other changes to the base confluence functionality. This is especially the case if you’re wrapping other macros. I ran into this problem with my Related Content User Macro (

Do you have any policies you use when building user macros?


David 4 years ago

Brad: I think this is the same problem you’d have with for example updating themes when the base functionality changes.

Luckily, this user macro is very easy to update if the base functionality changes. It is based on altering a stripping most of the functionality from


Mike 4 years ago

Hi – I get the following error:

Error formatting macro: list-attachments: com.atlassian.core.exception.InfrastructureException: Error occurred rendering template content

Running Confluence 3.1.1. Any ideas?




David 4 years ago

Mike: I’ve not had a chance to check and update this for Confluence 3.1 as yet — we’re still running 3.0.2. I’ll post an update and drop you a line when I do.


David 4 years ago

We’re now running this fine on Confluence 3.2 as is. I’m not sure why you get this error. Sorry.


Deepak 4 years ago


David, can you please give me a direction on how to sort the list as per lastModificationDate



David 4 years ago

Deepak: $content.getLatestVersionsOfAttachments() returns a java.util.List<Attachment>.

You need to sort the list of attachments using Attachment.getlastModificationDate().

It would be nice to add a sort by parameter to this user macro!


Lawrence Ong 4 years ago


do you know of a way to list all attachments in a space, on a page?



David 4 years ago

Lawrence: I’d probably suggest writing a plugin to do this, then do something along these lines…

  1. Get the spaceKey from the current page — page.getSpaceKey().
  2. List of all pages in the space
  3. Iterate over the pages, listing their attachments — page.getAttachments()
  4. Sort the attachments e.g. alphanumerically, or by date, type etc

Sturla 3 years ago

I’ve been looking for something like this for a while. But this does unordered lists only? I need to make it in alphabetic order. Is there a way to achieve this?


David 3 years ago

This doesn’t sort alphabetically. You could perhaps do some client side processing using javascript/jQuery e.g.

* Quick & dirty alphanumeric sorter
(function($) {
$.fn.azSort = function ()
me = this;

// Sort the list items
var listItems = $(me).children('li').get();
listItems.sort(function(x,y) {
var compareX = $(x).text().toUpperCase();
var compareY = $(y).text().toUpperCase();
return (compareX < compareY) ? -1 : (compareX > compareY) ? 1 : 0;

// Write the list items back to the DOM

AJS.$('.listAttachmentsDiv ul').azSort();

NB This code is untested, but a good starting point.


Eric R. 3 years ago

In confluence 3.4.7 this is returning
Error formatting macro: list-attachments: com.atlassian.core.exception.InfrastructureException: Error occurred rendering template content

Any ideas?


Daniel 3 years ago

This macro is beautiful.
But when I implement it in a page, there is always this line written before the macro is displayed:


and it is ticketed as a page.

What can I do to hide this line?


David 3 years ago

I’ve updated this macro a little. Please review the change.

Thanks, David


Tim 2 years ago

Thanks for this, its working nicely for me.


Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>