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:
- Edit the page.
- Click the image to see its properties panel.
- Choose Effects in the image properties panel and choose the Instant Camera image effect.
- Save the page.
- Choose Tools > Attachments to go to the “Attachments” view of the page.
- Choose Properties on the line that contains the image file name.
- 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. 🙂
Posted on 12 August 2012, in Confluence, technical writing and tagged caption, Confluence, image. Bookmark the permalink. 14 Comments.
ffeathers 
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 https://confluence.atlassian.com/display/DOC/Gallery+Macro 🙂
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.
Cheers
Sarah
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.
Cheers,
-Stefan
Hallo Stefan
Yes, it would be great if Confluence used a commonly-recognised element to store the caption. On the other hand, there’s quite a bit of debate on the web, about using the HTML title element to store captions. People are concerned about the accessibility aspects. Here’s an example of such a discussion: http://www.paciellogroup.com/blog/2012/01/html5-accessibility-chops-title-attribute-use-and-abuse/
People also mention the HTML5 figcaption element:
http://dev.w3.org/html5/spec/the-figcaption-element.html#the-figcaption-element
I’m no expert in this field. Do you have any further ideas on this point?
Cheers, Sarah
I am also no expert on accessibility, but it would make sense to have the title in a machine readable format (read: HTML attribute). Not only for the Scroll Exporters, but also for screen readers and for SEO..
Hi Sarah,
great tip! It would be very nice if all image styles supported captions, not only the instant camera style.
Cheers,
Stephan
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. 😉
Cheers
Sarah
Is there anyway to change the formatting of the text entered as the caption?
Hallo traci
I haven’t tried it myself, but it should be possible by adding CSS to your space. Here are the docs:
https://confluence.atlassian.com/display/DOC/Styling+Confluence+with+CSS
Cheers, Sarah
Thank you Sarah, I speculated that the change would be made there, but I wanted to verify before heading off into CSS Land.
These captions can be seen in your browser, but don’t appear in the pdf or html exports 😦
That’s true. If you really need the captions to be exported, you may want to have a look at the (commercial) Scroll Exporter Add-Ons, which do export the captions. More Info: https://marketplace.atlassian.com/vendors/7016
-Stefan
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-
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.