Back to blog

Templating Confluence for enhanced usability

March 18, 2009 - Posted in usability Posted by:

Tags: , ,

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

But…

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">
	...
	...
	...
</div>

Replace it with a table

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

		<td id="content" class="page $!mode">
			...
			...
			...
		</td>
	</tr>
</table>

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 {
	border-collapse:collapse;
}
#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.

11 Comments

Matt Hodges 5 years ago

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:

{pagetree:root=@self|startDepth=2}

Thanks again for sharing your work David!

Cheers

Reply

David 5 years ago

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.

Reply

Jarle Andersen 4 years ago

Hi,

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?

Reply

David 4 years ago

Jarle: It’s quite simple body { font-size: 120%; } or similar is a good start.

Here’s a good article on how to size text in CSS if you get stuck.

Reply

Matthew 4 years ago

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.

Reply

David 4 years ago

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.

Reply

Suchi 4 weeks ago

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. :)

Reply

David Simpson 4 weeks ago

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.

Reply

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>