A simpler way to view attachments in Confluence

…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: 2014-05-12
## View page attachments in a simple list
## USAGE: {list-attachments}
## @noparams
#set ($attachmentsList = $content.getLatestVersionsOfAttachments())
#if ($attachmentsList.size() > 0)
	    #foreach( $attachment in $attachmentsList )
	        #set ($currentAttachmentId = $attachment.id)
			#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:

David is a senior developer and solutions architect at AppFusions based in Nottingham, England.

AppFusions solves mixed-technology integration problems. We bring engineering and business workflows together, you can work better, faster and smoother.

AppFusions is headquartered in San Francisco, California and works with enterprise vendors and partners such as IBM, Jive, Egnyte, DropBox, Box and Atlassian.

  • Pingback: Atlassian Confluence()

  • Pingback: Dietmar Zipfel()

  • Pingback: Tweets that mention this post -- Topsy.com()

  • Pingback: bill arconati()

  • Pingback: John Sloat()

  • Brad

    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 (http://confluence.atlassian.com/x/LCOyCg).

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

  • http://davidsimpson.me/ David

    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

  • http://eduserv.org.uk Mike

    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

      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

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

  • Deepak


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


  • Lawrence Ong


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


    • David

      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

    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

      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.

    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

    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

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

      Thanks, David

  • Tim

    Thanks for this, its working nicely for me.

  • Paul

    This macro doesn’t work in Confluence 5+, does it? I’m a newb at this stuff and not sure what’s not working.

    I love the idea of this macro. I really wish I could figure it out.

    • http://davidsimpson.me/ David Simpson

      Hi Paul

      I’ve added ## @noparams to the user macro. It works on Confluence 5 now.