New documentation theme for Confluence wiki

Want an inbuilt table of contents for your wiki space? Lusting after a configurable header and footer? Hankering for sophisticated styling? You got it! Jens, one of the Atlassian developers, has released version 1.0 of his “Documentation Theme” for Confluence.

Actually, Jens is a product manager now but he still dabbles in development. We’ve already given him a doc choc reward from the technical writing team for his sterling work on the new theme. A theme is a “skin” for Confluence. It provides CSS styles, headers, footers and other custom features such as macros. Here is Jens’s announcement of his theme.

Friendly warning: The theme is still fairly new. At the moment, it’s available for Confluence 3.1 only. It’s not yet supported by Atlassian.

We’re test driving the theme in our own product documentation right now. It’s awesome!

Here’s what the Documentation Theme looks like

This is a screenshot of a wiki page using the Documentation Theme. If you like, you can click the image to see a larger version:

New documentation theme for Confluence wiki

In the above screenshot you’ll see a truly scrumptious left-hand panel:

• By default, this panel contains a search box and a table of contents (page tree) showing all the pages in your space. Actually, it shows the pages that are children of the home page. So you can “hide” pages by putting them at the root of your space. They will show up in the search results and people can see the content if they open the page, but the pages will not appear in the left-hand panel.
• The left-hand panel is fully customisable. You can choose to include or exclude the page tree and you can enter your own text, images and wiki markup.
• People viewing the page can drag the thick bar to increase or decrease the width of the left-hand panel. They can also remove the panel altogether, by clicking the somewhat cryptic icon at top right, next to the search box. I’m told that this icon is not so cryptic if you are a Mac user.
• Best of all,  the left-hand panel is part of the theme. So it will be upgraded whenever Confluence is upgraded. There’s no need to remove and then re-apply your customisations.

The page title is neatly above the page content, and not uncomfortably above the navigation panel as tends to happen when you insert the navigation panel yourself. The heading styles are slightly less naive than in the default Confluence theme. And note the rounded corners on the information and tip boxes. Ooh shiny!

I haven’t shown a customised header or footer in the above screenshot. The theme has them too. Below are some screenshots showing how you can customise them.

Downloading and installing the theme

First you need to download the theme plugin and install it onto your Confluence site. It’s not yet in the plugin repository, but you can get it from the Atlassian Plugin Exchange.

1. Download the JAR file from the Atlassian Plugin Exchange and save it somewhere on your computer.
2. Open Confluence in your browser and go to “Confluence Admin”.
3. Click “Plugins” in the left-hand menu.
4. Click “Browse” and find the JAR file that you saved in step 1. Select the file.
5. Click “Upload”. You should now see the “Documentation Theme” plugin listed on the page.

Now you can apply the theme to a space:

1. Go to “Space Admin” in the space where you want to apply the theme.
2. Select “Themes” in the left-hand panel.
3. Select the “Documentation Theme” and click “Confirm”.

Here’s a screenshot of the space themes screen, where the space is still using the Default Theme and the Documentation Theme is available for use. Click the image to see a larger version:

Customising the theme

This is magic. The theme works just fine as it is. But if you like, you can customise it:

1. Still on the “Space Theme” screen after applying the Documentation Theme to your space, click “Configure theme” in the yellow bit of the “Current Theme” section at the top of the page.
   
2. Select or deselect the “Page Tree” check box. This determines whether you get the default table of contents (page tree) in the left-hand panel.
   Hint: If you want to include your own content in the left-hand panel after the page tree, you can deselect the option here and then add your own page tree using the ??? macro in the “Navigation” text box.
3. Enter text, images and other wiki markup into any or all of the three text boxes:  “Navigation” is the left-hand panel; “Header” is a page header that will appear on all pages in the space; “Footer” is a page footer that will appear on all pages in the space.
   
4. Click “Save”.

That’s it! In the last screenshot above, there’s some wiki markup in the footer section, showing that you can even use the ??? macros to include re-usable content into your footer.

Update on 28 December 2009: I’ve just written another blog post about the ??? macro that is part of the Documentation theme. Space jumping lets you link from a page in one wiki space to a page with the same name in another space, without knowing the name of the page when you create the link.

Let us know what you think

Jens would be delighted if you add a review in the plugin exchange. I’d also love to hear what you think. Go wiki documentation.