Skip to end of metadata
Go to start of metadata

Draft in progress


We are developing this document as part of the November 2010 Atlassian doc sprint. Please treat the content with caution. It is draft and under development.

Welcome! This is a quick start guide for people who want to use images in Confluence. The following sections will provide tips and instructions on how to use Confluence's built-in features as well as plugins to handle images effectively.

  • Working with Images
    • General considerations when working with images — image formats (png, jpg, gif), file size of image, display size of image (readers' screen resolutions), etc.
    • Adding an Image to a page
    • Alt text for images
    • Attaching images versus rendering images from other pages
    • Reusing images - creating an image library
    • Using Confluence thumbnails and creating your own thumbnails
    • Making the most of the gallery macro
    • Annotating images using Gliffy
    • Drag and drop - from SnagIt and Skitch

On this page:

General Considerations

Before you start, there are a number of factors that you should consider when working with images on the web.

Image format is probably the first decision that you will be faced with. Should I save my images in png, jpg, gif, etc? Each format has advantages and disadvantages, such as the colour palette supported, the image quality preserved when compressed, support for transparency, etc. Your requirements will vary depending on how you will be using the images. We won't be describing each format in detail, but there are quite a few resources available online, like this article.

The display size and resolution of the image is another important factor. An image may look perfect on your monitor, but could be oversized and unwieldy on a smaller screen. What screen resolution are the majority of your readers using? If your wiki is publicly available, you can try enabling Google Analytics for your site to obtain this information.

Consider the size of the image files before using them in your wiki. Larger files obviously increase the time it takes for a page to load. There are a number of changes you can try, if your image file is too large, such as changing the image format, reducing the resolution and using Confluence thumbnails.

Finally, if you are displaying screenshots of a web application, the web browser that you take your screenshots in is also an important consideration. Again, consider what browser the majority of your readers will be using (Google Analytics can also provide you with this information). A familiar look and feel will help your readers grasp the context more easily.

Screenshot: Examining Properties of an Image in Paint Shop

Adding an Image to a Page

The Confluence documentation describes how to add an image to a page. The simplest way of doing this is by inserting the image into the page. This will attach the image file to the page and create a reference in the markup that will render the image when the page is loaded.

However, you can also reference an image from another Confluence page or even another website. This will force the image to be rendered in your page when your page is loaded. However, the image will not be attached to your page. For example, if you view the wiki markup for Adding and Removing Links in the Rich Text Editor, you can see that the images are actually rendered from the Space Attachments Directory page, e.g. '!Space Attachments Directory^LinkBrowserInsert.png|border=1,bordercolor=gray!'.

So, when should you attach an image to a page and when should you render the image from another page? Rendering an image from another page opens up the possibility of reusing the image. Updating a screenshot used in multiple pages is easy if you've referenced the image from a common page. The Space Attachments Directory page previously mention is actually used as an image library. However, you may want an image to remain static, e.g. screenshots on older release notes in a current documentation space. In this case, attaching the image to the page prevents the image from being accidentally updated and allows you lock it down with page permissions.

Using Confluence Thumbnails and Implementing Your Own Thumbnails

If your image is too large to display on your wiki page, you can use Confluence thumbnails to provide a smaller-image that displays the full sized image when clicked.

It is also possible to use a custom-sized of an image as its thumbnail. You may want to do this if the default thumbnail size is too large or small for the image that you want to display. To do this, you can use a combination of image and link rendering in Confluence as follows:


For example,


Note, when using this method, you won't get the lightbox when you click on the image. The image will load in place of the page instead.

Screenshots: Comparing default thumbnails to custom thumbnails

Full-sized Image

Confluence Thumbnail (click to view)

Custom Thumbnail (click to view)

Using the Confluence Gallery Macro to Display Multiple Images

Displaying multiple images can be useful when you want to show a sequence of related screens. Confluence's Gallery macro allows you to do this for a set of images. See the Gallery Macro page for instructions.

If you have an image library, you may want to reuse images from the image library in an image gallery. The gallery macro allows you to reference images from a different page, as follows:

{gallery:title=<gallery title>|page=<image gallery page>|include=image1,image2,image3,etc}

For example,

{gallery:title=My Screenshots|page=MyImageGallery|include=screenshot1.png,screenshot2.png,screenshot3.png}

Screenshots: Displaying a sequence of images using the gallery macro (click to view)

Creating Annotated Images

Annotating images can be particularly helpful for readers. However, annotated images can also create maintenance nightmares. You may have used an image editor to create a collection of annotated screenshots when a late user interface renders them obsolete.

The Gliffy plugin (not bundled with Confluence) is a tool for creating diagrams natively within Confluence. However, you can also use Gliffy to create an annotated diagram. Save your image as a jpg, attach it to the wiki page and create a new Gliffy diagram ('Add' menu -> 'Gliffy Diagram'). Your image will be available under the 'Page Images' section in the left menu. Drag it into your diagram and use text callouts to annotate it.

This makes it easier for you to create and maintain annotated images, as the annotations are not integrated with the image. If you need to update the image, just upload a new version of it to the page. Edit the diagram and the updated image will be refreshed.

Screenshot: Annotated image using Gliffy

Gliffy Zoom Zoom

Attaching Multiple Images to a Page

You can attach multiple images to a page in a number of ways. For example, you can navigate to the attachments for a page ('Tools' menu -> 'Attachments') and click the 'Add more files' link in the 'Attach File' section. However, if you need to attach a large number of images to a page (e.g. you want to update 20 files in your image libraray), this is an inefficient method.

Confluence supports dragging and dropping files onto pages. If you need to update a bunch of images, you could simply select the images in your file system and drag and drop them onto your page. Confluence will attach the images to your page, updating existing images with the same name. See Drag-and-Drop for more information.

If you have a very large number of images to attach, say 100, you could try using the WebDAV plugin to mount your Confluence pages and attachments as a network drive.

Screenshot: Dragging and dropping multiple images

  • No labels


  1. Re:

    "What screen resolution are the majority of your readers using?"

    That is not the crucial point: even if the majority get satisfactory results there could be an important and sizeable minority that get unsatisfactory results.


    What range of screen resolutions are your readers using?

    1. Awesome, thank you for the French translation, Felix!