How to add an image caption in Confluence

A customer, Chris Ridgeway, added a comment to the Confluence 4.1 release notes yesterday, saying that the release notes implied that you can add a caption to an image. But how? The good news is that you can do it, and it’s pretty snazzy once you know how!

In short: Use the “Instant Camera” image effect, and add your caption as a comment on the image attachment. (There’s a step-by-step guide later in this post.)

It took me half an hour to figure out how to do it. Like Chris, I was baffled. I applied the “Instant Camera” image effect, because the Confluence menu option implies that you can have a caption:

Then I tried clicking the image, double-clicking, right-clicking… Nada. So I tried going back into the image properties panel, in case another field had magically appeared there. Nope.

But I could see the caption in the screenshot in the release notes, so I wasn’t going to give up. Eventually I sat back and thought: If I were a Confluence engineer, what existing field or attribute might I decide to use as the image caption? I tried using wiki markup to insert the image, which gave me the power to add the HTML “title” and “alt-text” attributes – but they didn’t show up as the image caption.

Then it came to me: What about the attachment comments? Eureka!

Step by step

I’m using Confluence 4.3, and image captions have been available since Confluence 4.1.

Here’s how to add a caption to an image on a Confluence page:

  1. Edit the page.
  2. Click the image to see its properties panel.
  3. Choose Effects in the image properties panel and choose the Instant Camera image effect.
  4. Save the page.
  5. Choose ToolsAttachments to go to the “Attachments” view of the page.
  6. Choose Properties on the line that contains the image file name.
  7. Add a comment and save the attachment properties. My comment is “Yum!”

The text in your comment will appear as the image caption:

You’ll need to re-do the comment each time you upload a new version of the image.

And yes, I have now updated the documentation. Thanks Chris Ridgeway for asking this question and sending me on a mini treasure hunt. 🙂


About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 12 August 2012, in Confluence, technical writing and tagged , , . Bookmark the permalink. 14 Comments.

  1. Great tip, Sarah. The attachment comment can also be used as a caption with the gallery macro, as some brilliant tech writer has documented at 🙂

    • Hallo Tim

      Thanks, that’s a good point! I’ve added the word “caption” on the page for the Gallery macro, to make it come up in the search. The page previously referred simply to “comments”, not to captions.


  2. Hi Sarah,

    Great, hidden feature!

    If only the title was added as title-attribute this would be even more awesome – and the Scroll Exporters would pick up the page title automatically.


  3. Stephan Vollmer

    Hi Sarah,

    great tip! It would be very nice if all image styles supported captions, not only the instant camera style.


    • Hallo Stephan

      Yes, you’re right. Another limitation is that you can only add a caption to an image that is attached to a Confluence page. And it would be nice if the caption would persist across versions of the image.

      Still, it’s a great start. 😉


  4. Is there anyway to change the formatting of the text entered as the caption?

  5. These captions can be seen in your browser, but don’t appear in the pdf or html exports 😦

  6. It’s difficult to use, and one cannot replace the horrible font. Unfortunately, It looks like Atlassian won’t be fixing this issue, since a commercial addon exists-

  7. Wow! So very badly implemented – still. Thanks though for sharing Sarah.

    As BO noted, the font is horrible. Additionally, if your caption is too long it just truncates. I won’t be using this.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s

%d bloggers like this: