Showing results for 
Search instead for 
Did you mean: 
Sign up Log in

The Admin's tale - Adding an image to the page title


Once upon a time, the admin was asked once again for something, that Confluence was not providing out of the box.

A space administrator told him that his space includes pages belonging to five different topics. The space admin designed a great home page for his space and five logos for the five topics. People should recognize at a glance which topic each page belongs to. He wanted to add the images to the page title.

First, the admin tried to get rid of that requirement (he simply didn't have enough time, as always...). He told the space admin to add the logo to the page content itself. But soon, they found out that this was not the right place for a recurrent logo. The page design was terrible with that logo floating around somewhere and so, the admin had to think about the problem again. And this is what he found out:

What if one could add an image in front of the page title without changing the page title?

So, how can this be done? There is no built-in-feature like that and the admin didn't find a plugin that would do the trick. So he decided to create a small custom User Macro to implement this feature.

What are user macros? I explained this in my last article, so you can read it there, if you want to. 

The admin found out that the title of a Confluence page is displayed using a CSS style called "title-text". The idea was: Customizing this CSS style, so that not only the page title is displayed, but also a small image in front of the page title.

A space admin is able to adjust the CSS for the whole space globally but this did not work, because there should be different images for the different topics and also pages without images at all. There were some main requirements for implementing the solution:

  • Adding CSS directly with the editor is not allowed
  • There should be different images available for the page (or none)
  • The user must not know the URL of the images
  • Only predefined images should be used  

Implementing the macro

The admin created a new User Macro called "page_title_image":



The macro has no macro body, just one enum parameter for the image and values for each possible image. The different images were added as atttachments to a Confluence page, the "image store". The admin copied the URLs of these images from the attachments list of the page and added it to the User Macro as enumValues:

## @param 0:title=Image-URL|type=enum|enumValues=h t t p : / /,h t t p : / /,h t t p : / /|default=h t t p : / /

(I added blanks to the "http://" so they are not represented here as link)

And then, the user could select from the different available images as follows:


But how is this image added in front of the page title?

The admin performed a little bit of CSS magic, waved his wand and wrote the following User Macro Template to add the CSS to the page:

#title-text {
background-image: url('$param0');
background-repeat: no-repeat;
padding-left: 40px; /* width of image plus margin, may be different in other systems */
display: block;


  • This script is adding the stylesheet to the Confluence page.
  • The stylesheet puts the selected image in front of the page title.
  • The page title remains the same as before, of course.

And this is how it looks on the Confluence page:


 The space admin was happy, as well as the Confluence Admin and the User Macro was heavily used until now.

... and they all lived happily ever after.  

And here is another Admin's Tale: Fun with labels, not with flags


Dchosen December 7, 2018

Nice article Thomas..! I wanted to know if there is a possibility of having image uploaded from the local system like the files & images macro work. I tried using the url of the image I uploaded to a page. I am landing on the rendering error.

Error rendering macro 'page_title_image'

[com.ctc.wstx.exc.WstxLazyException] Unexpected character '=' (code 61); expected a semi-colon after the reference for entity 'modificationDate' at [row,col {unknown-source}]: [4,138]

Can you please  advise.

Katie Crick September 27, 2019

Thank you for the info.

Does the image by chance show in the dropdown in the top-right Search?

Natalia Glinka September 7, 2020

Hello Andreas,

I find this macro really useful. However, I've encountered one problem - the icon I've uploaded gets too big! It's stretched as the whole background... I don't know how to adjust the picture so that it looks like in the example you've showed. Could you please help?


Thank you!


Graciele Pereira April 14, 2021

Hi Thomas, 


Excuse me for being ignorant, but which menu do I enter to access and create these macros?

lujmo August 31, 2022

@Graciele Pereira  see

 Does anyone know if it is possible with css to make the page title fit the size of image ? .. eg say i have a large "header" style image and I want to page title section to expand to fit that 

Nanda Hareesh Kumar March 6, 2024


A user macro script to filter table content is a good idea. But this script is only useful for fetching data through text matching. It does not allow user to filter data based on header.

For example, I want to filter the data based header.

like Unit Test Status = Done.

Is it possible to filter the data.

IDUnit test statusfunctional test status
1001WIPTo DO
1003To DOIn Review
1005In ReviewDone
1006WIPTo DO
1008To DOIn Review
1010In ReviewDone


Can anyone help me with this?



Log in or Sign up to comment
AUG Leaders

Atlassian Community Events