Templating Confluence for enhanced usability

I love Confluence. It’s simple. It’s easy to use. It’s hierarchical, so you can build a nice structure.


I hate Confluence. I can’t find anything. Ever. It’s hierarchical, but which branch in the hierarchy is my content located in? Damnit, the Lucene powered search doesn’t seem to be able to find what I’m searching for.

My main gripe with Confluence is that by default it uses breadcrumb trails as primary navigation contrary to breadcrumbs best practices. They are no replacement for the real deal.

Breadcrumbs are secondary navigation designed as an alternative to the main navigational scheme. As such they give no context to relate the current page to others at the same level in the hierarchy. Breadcrumbs cannot aid in navigation within a level. So using breadcrumbs as primary navigation leads to a lack of awareness of the structure of the website/wiki space and thus confusion.

With this in mind, I decided to add a consistent primary navigational scheme to our global Confluence template. As Atlassian have in the past been known to change the templating scheme a little on upgrade to newer versions of Confluence, it is important to limit the changes to be as minimal as possible to limit ongoing templating maintenance issues.

Templating changes

These are limited to…

  • Replace the main content div with a 2 column table based layout (I know, that’s a somewhat naughty, but I’m a realist and in a hurry – Confluence already uses tables for some aspects of layout)
  • Add a {pagetree} to the left hand column for primary navigation
  • Replace a few icons in the {pagetree} macro to be a bit more Mac, a bit less Windows
  • Add a custom/override stylesheet

I’m using the {pagetree} macro, but I’m not overly fond of it. Ideally, I’d like it to expand siblings and children of the current page by default. But again, I’m not interested in rolling my own navigational system. Rather I’ll make do and mend what’s available. It does an adequate job, but looks a bit ugly.

Edit Site Layouts | Page Layout

Find this content div:

<div id="content" class="page $!mode">

Replace it with a table

<table id="myContent">
		<td class="myNavigation">$helper.renderConfluenceMacro("{pagetree:root=$space.homePage.title|startDepth=1}")</td>

		<td id="content" class="page $!mode">

I’m not proud of adding a table for layout, but it much less bad than the markup I’ve seen produced by some third party theme building plugins.

Global Stylesheet

Add a custom/override to the default stylesheet:

body {
	width: 90%;
	min-width: 750px;
	/*max-width: 1000px;*/
	margin:0 auto;
	height: 100%;
	background-color: #fff;
h1, h2 ,h3, h4 {
	font-family: Calibri, Arial, "Helvetica Neue", Helvetica, sans-serif;
	line-height: 1.25;
	margin: 0 0 .25em;
#header {
	margin: 0;
	padding: 3px 6px;
	background: #fff url(/images/my-images/backgrounds/menus/blue03.png) repeat-x;
#main {
	border: 0;
	padding-top: 30px;
#com-atlassian-confluence h1#title-heading img.space {
	margin-right: 10px;
	margin-left: 320px;
#myContent, #myContent  td {
#myContent, #myContent td td {
	border: 0;
#myContent {
	margin: -87px 0 0 0;
	background-color: #fff;
#myContent tr {
	vertical-align: top;
#myContent .myNavigation  {
	width: 270px;
	min-width: 270px;
	padding-top: 100px;
#myContent .myNavigation a {
	text-decoration: none;
#myContent .myNavigation ul ul {
	padding-left: 0;
	border-top: 1px solid #ccc;
#myContent .myNavigation ul ul ul {
	padding: 0;
	border: 0;
	margin: 10px -8px 0 -8px;
#myContent .myNavigation ul ul ul ul {
	margin: 0;
	padding: 0;
#myContent .myNavigation ul ul li {
	border-bottom: 1px solid #ccc;
	padding: 8px 8px 0 8px;
	background: #fff url(/images/my-images/backgrounds/menus/grey01.png) repeat-x;
#myContent .myNavigation ul ul ul li {
	border: 0;
	padding: 3px 8px 3px 20px;
	background-color: #ccc;
	background-image: none;
#myContent .myNavigation img {
	margin-right: 2px;
#myContent .myNavigation span img {
	display: none;
#myContent #content {
	padding: 100px 10px 10px 50px;
#myContent #content #editpageform {
	width: 100%;
#myContent #content .page-metadata {
	color: #999;
#myContent #content .wiki-content > .panelMacro {
	margin: 10px 0;
#footer {
	display: none;

Additional and replacement images

I’ve replaced the following images used by {pagetree}.

  • /images/icons/tree_plus.gif
  • /images/icons/tree_minus.gif
  • /images/icons/tree_square.gif

This will have the side effect of making all {pagetree} icons more pleasing to look at.

I’ve added the following backgrounds:

  • /images/my-images/backgrounds/menus/blue03.png (for the breadcrumb trail /search bar)
  • /images/my-images/backgrounds/menus/grey01.png (for the primary/left-hand navigation)

Resulting Look and Feel

This is just a work-in-progress, but gives a marked improvement in usability due to the enhanced navigation.

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: Matt Hodges()

  • http://www.atlassian.com Matt Hodges

    Great post David! Your new layout looks hot :)

    We do have some documentation on how you can modify the layout of Confluence out-of-the-box to achieve a look similar to our Confluence Documentation (not nearly as sexy as your’s though!).

    Regarding the Pagetree macro, it is possible to specify a starting depth using the ‘startDepth’ parameter. For example:


    Thanks again for sharing your work David!


  • Pingback: Keith Brophy()

  • David

    Matt: Thanks for your comment. I kind of used the Confluence Documentation pages as a starting point.

    I think it would be great if Confluence had a template similar to this out of the box – there are a great number of people who don’t want to do any customisations at all, no matter how straightforward.

  • Pingback: Matt Hodges()

  • Jarle Andersen


    I am a satisfied Conlfuence user

    I like your styling. Not being familiar with css, I have simply copied the CSS for your headings and added “body”. How do you set the font-size for body text?

  • http://helpdesk.missouristate.edu Matthew

    What do you think of the Documentation Theme Atlassian has released this year? We’re using it at http://experts.missouristate.edu/display/csvhelpdesk and are quite pleased with it.

    • David

      Matthew: I agree. Jens Schumacher’s Documentation Theme pretty much fixes all the gripes I had about Confluence. He’s done a great job and I really think that it should be the default theme when you install Confluence.

  • Suchi

    Thank you so much for documenting this! We’re using Confluence and Zen Foundation. I was looking on Atlassian Answers for how to style the pagetree, and wasn’t able to find anything. Using your sample CSS, I was able to add my own to the Zen “brand” and et voila. :)

    • http://davidsimpson.me/ David Simpson

      Hey Suchi, it’s good to know that this post is still vaguely relevent. A lot has changed in Confluence (and for the better) in the years since this post was written.

  • Kids Fire Gear

    My brother recommended I might like this website. He was
    once entirely right. This publissh trulyy made my day.
    You cann’t imagine simply how much time I had spet for
    thhis information! Thanks!