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

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:

New documentation theme for Confluence wiki

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.
    New documentation theme for Confluence wiki
  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 {pagetree} 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.
    New documentation theme for Confluence wiki
  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 {include} macros to include re-usable content into your footer.

Update on 28 December 2009: I’ve just written another blog post about the {spacejump} 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. ๐Ÿ™‚

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 12 December 2009, in atlassian, Confluence, technical writing, wiki and tagged , , , , , , , , . Bookmark the permalink. 48 Comments.

  1. Started drooling the moment I saw it. Our company has it installed and is loving every minute of it. Very super excellent.

  2. Could you explain how to edit the Page Layout of this theme so that changes apply globally to all spaces?

    I tried to do Look & Feel | Layout | Page Layout but it tells me I cannot edit currently active themes.

    I’d like to add some macros to the left nav per instructions on other Left Navigation pages.



    • Hallo Mark

      It’s true that you can’t edit the “page layouts” if you have a theme installed. You can only edit the layouts (at space or site level) if you are using the default theme.

      Luckily, the new theme provides an even better option. ๐Ÿ™‚ To add macros and other content to the left-hand navigation bar, you can use the “Configure theme” option. This works at site level as well as at space level.

      I hadn’t tried it at site level before, so thanks for asking this question! To do it at site level, first install the theme. Then go to “Administration” –> “Themes” (in the “Look and Feel” section of the admin left-hand navigation panel). Choose the “Documentation Theme” as the new theme for the entire site. Then click “Configure theme” in the yellow box. (It looks much the same as the screenshot in my post above, which is for the space-level config.)

      Now you can enter macros, text, images and any wiki markup in the three text boxes: “Navigation”, “Header” and “Footer”.

      Cheers, Sarah

  3. Jens now has a new issue tracker for the Documentation theme. If you have any requests or find a bug, he’d be delighted to hear from you. ๐Ÿ™‚

  4. Hi Sarah,

    Thank you for this very nice theme.

    For our company wiki we are using the subscpaces plugin for easier navigation through the spaces and the approval workflow for the QM section. I have setup a test environment and modified your documentation theme by adding:



    to the “main.vmd” decorator.

    Moreover I modified the “main.vmd” and the “page.vmd” decorator according to the guidelines of

    Both seems to work fine and extends the functionality of the theme. Maybe you could take into account using these modifications in a future release.

    Finally, I tried to replace the search box of the pagetree by a livesearch and adding a link to the home page of the particular space into the navigation bar. As I am trying to use the theme as general theme I failed to add generic references the space key and space home page.

    By modifying the “page.vmd” as following I succeeded:


    In general this work, but in the “attachment view” $spaceKey and $space.homePage.title are not correctly rendered resulting in an error message in the navigation bar. Do you have an explanation and/or a solution for that?

    Cheers, Thomas

    • Hallo Thomas
      That’s an interesting setup! I’m afraid that I don’t know the answer to your question. I think you may get some help if you try the Confluence developers’ forum:

      As I understand it, you’re using the Documentation theme at site level, and you need a variable space key so that you can put it into the Live Search. You can’t use the {spacejump} macro because you can’t embed one macro into another macro. It seems like you’ve already gone a long way to achieving what you want. I hope someone in the forum will have an idea.

      Cheers, Sarah

    • Hi Thomas,

      I’m just trying to use the horizontal menubar of the subspaces plugin with the documentation theme, too. So I switched to the standard layout and modified the main.vmd as described in the subspaces plugin documentation. In the standard layout the horizontal menubar is displayed correctly but when i switch back to the documentation theme, the horizontal bar does not appear anymore. How did you do this? I use Confluence 3.1.2 and Documentation Theme 1.0.4.


  5. Hi guys,

    I was running the Blackberry plugin with the Documentation theme and was getting a blank footer at the bottom of the screen. It was just a white bar.

    Once I removed the Blackberry plugin the blank footer was replaced with the evaluation and Atlassian footers.



  6. Hallo Steve

    Thank you, that’s useful information. I’ve posted a copy of your comment in the forum, in case it’s useful to other people too:

    Cheers, Sarah

  7. Hi there Sarah, Steph, from Paris France here ๐Ÿ˜‰

    I have a question regarding the way to handle documentation versioning on Confluence.

    Our current version is 3.0.0, although we should upgrade to 3.1 in early Feb.

    I’ve read an old post of yours on this blog stating that you needed to create one space for each new version of your documentation set.

    In my company, we (are trying to) use wiki pretty much like a content management system, although we do understand it’s not designed (yet? ;-)) as such.

    We use it as a repository to store content which we use to build training material, under the form of PDF, using CSS extensively. The result is pretty professional.

    We try to isolate each wiki page as a topic, keeping roughly a DITA-aware approach, although we’re not writing content in XML, but this way, we will be able to reuse content, when appropriate, that does not change from one of our software version to the next one, and so on.

    We don’t use many macros, apart from {section} ;{column} and {include}. We inject some custom made {html-page break} CSS macros in the wiki page so that the resulting pdf is laid out nicely. I do this this way because it’s easier for me to ask for some internal help in CSS rather than in XSLT.

    That was the background information you might need to know before what’s next ๐Ÿ˜‰

    For our training content in wiki, and given the way Confluence works, we need to add a version label to each page we write because its content might change from one software version to the other and since we cannot have pages with the same title in one space, we need to:
    1/ create a new space each time we move from one software version to the other
    2/ consequently use {include} macros to include non changing existing content in addition to new content based on that software version

    Doing so, we’ll end up having a huge list of spaces for each version which are listed together with the other spaces used in the same wiki by other people who have nothing to do with it, hence a little unnecessary “pollution” from our part…

    How do you handle this?

    We’re thinking of buying a new Confluence license just to store content according to our versions.
    Is this what you do for all the versions of you documentation sets?

    Do you know if it’s possible to create sub-spaces of one space?
    OR Do you know it it’s possible to hide spaces so that they’re not listed together with the other ones?

    Are there any plans to enhance the editor and allowing us to write content in xml?

    I know I could just post a comment on the confluence forum or enter an enhancement
    But since we’re doing the same job and you work there, I think you might as well be the bets inside person to ask all those questions ๐Ÿ˜‰

    Thank you very much in advance!

    • Hallo Steph

      Aha, you’re doing release management on a wiki. Interesting and challenging. ๐Ÿ™‚ The situation you describe is very similar to ours, except that we don’t use {include} macros to include non-changing content from one version to another.

      We do use {include} macros for content reuse, but we limit this to reuse within the same version of the documentation.

      We do create a copy of the space for each major version of the product, such as going from version 1.0 to 1.1 or from 1.1 to 2.0. All the content is therefore duplicated in the copy. Our philosophy is that we don’t plan to update the content for the previous versions of the product, so the duplication of content is not an issue. And it can work to our advantage, because we can just change the content for the new/updated features in the new release without worrying about affecting the docs for the previous release.

      For minor releases, such as going from 1.0.0 to 1.0.1, we do not create a separate space. Instead, we make notes in the docs themselves if necessary, e.g. “this fix is available in version 1.0.1 and later”. Our philosophy here is that the minor releases are principally bug-fix releases and there are very few feature changes.

      We have not yet found a solution for the problem of having multiple spaces for the same product, each for a different version. There is no way to create a space within a space. One thing that we do to mitigate the effect is to have a search box inside each space, that yields search results from that space only. So when the user searches the docs for a particular product and version, they get search results within that space only. We use the {pagetree} or the {pagetreesearch} macro for this search. You can see this in action here — see the search box on the left:

      Another strategy, that we have not yet implemented but probably will soon, is to archive off the spaces for the older versions of the product that are no longer supported. If we do this, we will find out from our support team what the official support policy is e.g. do we support all versions over the last two years, or the last n versions of the product? Then we will create PDF, HTML and XML versions of the older spaces and make those available to the customers (actually, we do that already) and then remove the older spaces from the wiki.

      Ha ha, the “enhance the editor” question! There are constant discussions and spikes around using XHTML instead of wiki markup for the editor, but there is not yet any definite plan, timeline or intention to do this.

      I hope this helps. Thanks for the detailed comment! I’m so glad your training material emerges from the wiki looking pretty professional. Awesome!


  8. Vertical scroll bar disappears when I create a new page using a template.

    Hi guys,

    When I create a new page using a template the vertical scrollbar on the edit page disappears. You can still scroll up and down using the wheel mouse, or if you look closely you can just see the edge of the scrollbar and click on it.

    Screenshot attached to forum post –

    I am using Firefox 3.0.17.

    Is anyone else having this problem?



  9. hi guys,
    I’m trying to convert pages from moinmoin 1.2.3 to confluecne 3.1.1 using UWC 3.11. i would like to have the themes which ‘re available in moinmoin, has to be appeared in confluence also.Plz let me know how to do that asap.

  10. The Documentation theme looks great and we would like to use it on our University Wiki for all spaces. However, the theme appears to ignore changes made to our global Main Layout. We were under the impression that changes made in the global “Site Layouts” via the Confluence admin apply to all themes — not just the default theme.

    Thanks again for providing this great theme alternative.

  11. Hello Sarah,
    I would like to prepare a report for a software engineering conference. My idea is to describe how a Wiki system can be effectively used for documentation in agile projects. I would like to demonstrate some key features and practices of documentation process in Confluence.
    May I do it, as you think? You can read a bit more on this idea on my blog:

    • Hallo Katya
      That’s an awesome idea. You’ll be a star. I’ve added a comment to your post too. Good luck with the presentation!

  12. Jeff Coatsworth

    Hi Sarah,
    Liked the look of the theme so much that I downloaded the eval version of 3.2 to try it out. However, the lack (at least to me) of any sort of HTML page converter (I wasn’t finding one anywhere) means that there’s going to be too much manipulation of content to be viable in my operation.
    Too bad – I was really looking forward to taking the HTML that RoboHelp produces (we use the Adobe Tech Comm Suite to single source everything) and sucking it into Confluence. Confluence looks like it can beat Adobe’s AIR output for commenting via the web – but if you can’t get your content into it easily, then it never gets to shine.

    • Hallo Jeff

      Yes, I agree that it’s a real shame there’s no easy and reliable way to convert HTML documents to Confluence. It’s one of those requests that’s just not on the wiki development team’s roadmap, due to higher priorities.

      One possibility is to publish your documents to Word and then convert from Word to Confluence using WebWorks ePublisher. I wrote a blog post about some minimal experimentation I did with ePublisher. You’ll notice from the comment train that a few other people have been experimenting too, and that Ben Allums from WebWorks has given some useful responses there too.

      Another contact that you may find useful is Gina Fevrier. She recently wrote a blog post called Getting ready to launch our user community with the Confluence wiki, blogs, and user forums. In her post, she explains that she’s recently run a project to convert their documentation from Flare and RoboHelp to Confluence. I’m not sure if it was a once-off conversion or if they’re still planning to single-source the docs in RoboHelp. She’ll be presenting her findings at the STC Summit in Dallas in May, then publishing them after that. I’m sure she’d have some useful information for you.


  13. This is great theme. How do I change the sort order for the items in my page tree? These seems possible from the examples I’ve seen but I don’t see how.


    • Hallo Kevin

      You can reorder your pages in the space. It’s not really changing the sort order, in the sense of changing from ascending to descending or from alpha to number. Instead, you can put the pages where you want them and they’ll stay there.

      There are two places where you can reorder the pages. The first is better if you want to reorder a number of pages: Open the space’s ‘Browse’ menu and select ‘Pages’. Then click the ‘Tree’ tab. Now you can open the branches and drag and drop the pages into the positions you want. If you move a parent page, all its children will move too.

      The other way to change the position of a page is to go to that page, open the ‘Tools’ menu and select ‘Move’. If you want to, you can first choose a new parent page, or you can just leave the parent page as it is. Then put a tick in the ‘Reorder’ checkbox at the bottom of the popup window and click ‘Move’. Now you can move the horizontal bar up and down the list of pages, to pick a new position for your page.

      The second option is also available when you’re editing the page. And the second option may be better if you have a very large number of pages in your space, because the page tree can be difficult to use in large spaces.

      All this is assuming you have Confluence 3.2. ๐Ÿ™‚


      • Thanks Sarah. That’s a big help.

        For your reference, the first option works with 3.1 but not the second. Luckily, at this point my space size is pretty manageable so its not an issue (yet).


  14. Is it possible to add more colours and pictures? It’s very nice and easy to use but a little bland for my blog.

  15. I’d like to see this great theme with more colour too. Look forward seeing your response to Laura’s question above. Thanks.

  16. Hallo there Laura and Gold Coast girl

    There are a few ways to change the colours and the look and feel of a space theme.

    You can change the colour scheme of the space, or of the entire Confluence site. There are some guidelines here:

    For more in-depth changes, you can edit the space’s CSS style sheet. You need a fair bit of CSS knowledge to do that, and the CSS itself is specific to the theme used. Here are the guidelines:

    Here’s how to change the space logo:


  17. Hi – I want to change over to the Documentation theme – but I cannot get the colour scheme to work for the headers. (When I click on the colour picker – a blank box displays – and even if I put in a new colour code – it doesn’t change the headers). I’ve tried changing it both globally and locally and it doesn’t work. Can you help? Thanks a lot.

    • Hallo mumpy
      I’ve had a look in the Confluence issue tracker, and yes indeed there’s a known bug in the Documentation theme. Here’s the bug report:

      If you like, you can sign up for a user ID on the issue tracker, then “watch” the issue to get notifications on any progress made. You can also vote for the issue and add comments if you like.


  18. We’ve just started to use this (great) theme on Confluence 3.2.1_01 in custom form, but we’re having an issue with the position of the “Expand All” and “Collapse All” links that can be created via the {pagetree} macro, i.e.


    I’ve created a Confluence bug about this where you can see a screenshot of the problem:

    We believe it to be a CSS issue…

    Any tips? Thanks.

  19. Apologies, the Jira bug in the above comment is WRONG. it should be:

    • Hallo James

      Ah, that’s an interesting one. I hadn’t tried using the “expandCollapseAll” parameter with the {pagetree} macro before. I’m guessing no-one else has tried it in the Documentation theme either, so you’re a pioneer. ๐Ÿ™‚

      You’ve done the best thing, in raising that JIRA ticket. I’ve voted for it and added a comment too, after testing on Confluence 3.3.3.

      As far as workarounds are concerned, I can’t think of anything ideal. I tried adding the following code into the config for the left nav panel:

      The above code wraps the {pagetree} in a column, and inserts a column with a width of 1 pixel to the left of the page tree. It works, but 1 pixel is too much, so it doesn’t look all that great. You can, however, see the whole of the word “expand”. ๐Ÿ™‚

      Another way is to use this code:

      The above code wraps the {pagetree} macro inside a {panel} macro. I set the background and border colours to white, but you could choose any colour you like. Again, this is not ideal because the styling of the {panel} macro replaces the left-hand nav styling.

      Let me know if you think of anything better! In the meantime, I’ll ask the other technical writers at Atlassian to vote for your issue too. ๐Ÿ™‚


      • Hi Sarah,

        Sorry for the length of time taken to reply – yes seems I was pioneering here!!

        The workaround suggested in the Jira does work well, but I’ve not had time to try your suggestions.

        I really like the Documentation theme – works very well for us. There are some fundamental differences between display in Internet Explorer and Firefox though – Firefox gives a far superior look (you get the nice rounded edges to the Info and Notes boxes for example)… Have you experienced this?

        Many thanks and great blog…

        We are now looking at how to implement versioning of our different documentation sets using spaces… ๐Ÿ™‚

    • Hallo James

      Yes, I’m afraid IE is a bit of an ugly sister with respect to UI prettiness. Now that you mention it, I do see that the rounded corners are just not there!

      Very cool, that you’ll be using spaces for version control! I guess you have discovered the “Copy Space” plugin. That’s what we use to create the new space for each successive version of the product.

      Let me know how it goes.


  20. Interesting theme, i’m just starting to have a good look at it. Customising seems to be fairly straight forward. I’ll comment later with some in depth feedback after exploring it further. Cheers.

  21. Hello Sarah
    We are using this great documentation theme but had some complaints that the menus do not work in IE7. any tips or comment about how this can be fixed.
    ex: when i hover on Browse, or +Add or Tools the menu doesn’t automaticaly appear while it appears in IE8 or FF.

    • Hallo Younes

      That doesn’t sound good. ๐Ÿ™‚

      I see that you’ve already found the issue tracker for the documentation theme, and added a comment to its wiki. That’s a great start.

      Because the theme is now part of core Confluence, you can also raise an issue directly in the main Confluence issue tracker:

      I’ve done a quick search there, to see if anyone else has reported the problem. I didn’t find a matching issue, so it would be a good idea to raise it there, giving all the information about your environment, the version of Confluence you’re using, and so on. Also let us know whether the problem affects all your spaces, or only the spaces that are using the Documentation theme.


  22. Hi Sarah,
    I can’t figure out how to display icons in the left hand panel. Can you help?
    Thanks very much, Mumpy

    • OK – I used regular html code and it worked.

    • ok – figured it out – now onto the next thing!

      • Hallo mumpy ๐Ÿ™‚

        Yes, regular HTML code will work, if your wiki is configured to allow raw HTML.

        Another way is to use wiki markup in the left-hand panel. Confluence has specific codes for some emoticons and symbols, such as a smiley, a check mark, a star, and so on.

        For more complex icons, you can upload a picture as an attachment on a Confluence page. Then use wiki markup to embed the image into the left-hand panel, like this:

        Hope that helps!
        Cheers, Sarah

  23. Yep – I uploaded a picture as an attachment and then then used wiki markup to embed it – plus I added a link so that when you click on it – you go to another space. (Hurrah for me!)

  24. Is there a way to change the background color of the whole left pane?

  25. Hello,

    I’m wondering if there is a way to use the slider functionality elsewhere, specifically in the Adaptavist Theme Builder if possible.

    Graham Mueller

    • Hallo Graham

      I’m not very familiar with the Adaptavist Theme Builder, so I don’t know how easy it would be to add your own left navigation bar or to make it a slider.

      Before Confluence had the Documentation theme, we documented a way of adding the table of contents to a panel on the left. It involves editing the page layouts. This is only possible if you’re using the default theme. Here’s the documentation, in case it’s useful for your setup:

      Another suggestion is to try posting your question in the Confluence users’ forum, to see if anyone else has already tried doing what you want:

      Let me know what happens. ๐Ÿ™‚

      Cheers, Sarah

  26. Thanks for the article Sarah.

    Question: Is there a “switch” or javascript or tag I can use on a PER PAGE basis to show\hide the left nav.?


    • Hallo Royce
      That’s an interesting question. It could be useful to suppress the left-hand panel on specific pages, such as the front page. I don’t know of such a switch. As you probably know, there isn’t one on the UI. You could examine the page source, and click the show/hide button to see if the change is visible in the JavaScript. Another idea is to ask the question at the new community forum: http:// I’d be interested to see the response too.
      Cheers, Sarah

  1. Pingback: Space jumping in a wiki documentation theme « ffeathers — a technical writer’s blog

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: