Blog Archives

Confluence tip – how to hide child pages in the Documentation theme

This hint is for people who are using the Documentation theme in Confluence wiki, and want to hide the child pages that are shown at the bottom of every page. After all, the left-hand navigation bar in  the Documentation theme shows a page tree, including all parent and child pages. So it’s probably overkill to show the children at the bottom of every page too.

Confluence tip - how to hide child pages

To hide the child pages, add some CSS to the space. This is the CSS you need:

#children-section{   
display:none;   
}

I’ve tested the above CSS in Confluence 4.3 and 5.0.

To add the CSS to your space, you need space administrator permissions. Go to BrowseSpace AdminStylesheet, edit the stylesheet and dump the above code into the text box.

The documentation has more guidelines on using custom stylesheets: Styling Confluence with CSS.

Have fun!

Why don’t my pages appear in the Documentation theme’s table of contents?

What if you are using Confluence wiki’s spiffy new Documentation theme but the left-hand navigation bar doesn’t show any pages? Or maybe some of your pages are there but others are missing. This can be confusing, even downright terrifying, for any technical writer. 😉

The wiki Documentation theme is something we technical writers have been wanting for a long long time. I blogged as soon as the first version appeared. We even said thank you with chocolate to Jens, the developer who created the theme! It has a built-in table of contents, configurable page header and footer, and the sort of sophisticated font styling that makes our documentation look awesome. The theme comes bundled with Confluence 3.2. If you have Confluence 3.1, you can install the theme yourself by downloading and installing the plugin.

Here’s what a wiki space looks like when using the Documentation theme. (Click the image to see a larger version.)

Why don't my pages appear in the Documentation theme's table of contents?

Why don't my pages appear in the Documentation theme's table of contents?

See the stupendous dynamic table of contents on the left? OK, so that’s what it should look like. All the wiki pages are obediently showing up in the left-hand navigation bar.

But what if they don’t? Here are the three possible causes that I’ve come across.

The pages must be children of the space’s home page

Each space has a single page designated as its “Home” page. The theme constructs the table of contents from all pages that are child pages of the space’s home page. If your pages are at the same level as (i.e. siblings of) the space home page, they will not appear in the left-hand navigation bar.

More background: The theme uses the {pagetree} macro to produce the table of contents on the left. When you use the {pagetree} macro on a page, you can choose the top page to be displayed. The Documentation Theme chooses the space home page as the top page.

The fix: If this is the cause, then there are two ways to fix the problem.

  • You can change the designated space home page for the space. You need space administrator permissions. Go to “Space Admin” and select “Edit Space Details”.
  • Or you can drag and drop all your pages to make them children of the current home page. Go to “Browse”, “Pages” and click the “Tree” option.

How would your pages end up as siblings of the home page, or at the root level of the space?

  • It may happen if you use a tool to import your pages from another source. For example, Gina Fevrier pointed out this problem when she was experimenting with WebWorks ePublisher to import content into Confluence. Ben Allums from WebWorks was in on it too. Here’s our exchange of comments. Thanks Gina and Ben! Update on 17 April: ePublisher 2010.1 was released a couple of days ago, on April 15. With this new version, you an specify the parent page in Confluence. When you import your content, all the pages will become children of that page. See this comment for Ben Allum’s guide on how to to this in ePublisher.
  • If someone clicks “Add” to add a page while in the Space Admin screens, Confluence will add the page at the root of the space.
  • People may move the pages to the root of the space, either by accident or intentionally. (It’s often useful to have pages in the space that don’t appear in the table of contents.)
  • Someone may change the designated home page for the space.

All the modules of the Documentation theme plugin must be enabled

A weird bug may flit in when you upgrade to Confluence 3.2. It happened to us, and we don’t know why, so it may happen to you too! We were running our documentation wiki on Confluence 3.1 with the Documentation theme installed separately as a plugin. Then we upgraded to Confluence 3.2. Then the technical writers rushed down the stairs to the Confluence development team:

Hey dudes, the upgrade has broken the documentation spaces. All the pages have disappeared from the left-hand navigation bars!

We found the cause of the mass vanishing act: One of the theme’s “modules” was disabled. So it was an easy fix — just enable the module again. But we still don’t know why it happened. Here’s the knowledge base article: Documentation Theme Fails to Display the Navigation Bar after Upgrading to Confluence 3.2 or Later.

I think the wording of the KB article is quite cute:

We believe this issue is caused by a subtlety related to how the configuration is migrated between the versions.

That means, “We don’t have a clue why this happened, but it did.”

The fix: You need to be a Confluence administrator to fix this one. Go to “Confluence Admin”, select “Plugins” and select  the “Documentation Theme” plugin. All the modules should show up as enabled, like this:

Why don't my pages appear in the Documentation theme's table of contents?

Why don't my pages appear in the Documentation theme's table of contents?

If one of the modules, such as “Velocity Helper”, is disabled it will be a bothersome pinkish colour instead of a calming green. The word next to it will be “Enable” instead of “Disable”. You know where to click. 🙂

Perhaps you clicked the sidebar icon and got rid of the table of contents altogether

The sidebar icon looks like a lopsided window: It’s perched a bit uncomfortably next to the search box at top right of the screen. Click it to get rid of the left-hand navigation bar. This is very useful if you need to use the full width of the screen to see the page content. But it’s easy to forget that you clicked it, especially as it remembers its state next time you visit Confluence.

The fix: Click the sidebar icon Why don't my pages appear in the Documentation theme's table of contents? again. (It looks a bit dimmer when the left-hand navigation bar is hidden.)

Maybe there aren’t any pages in your space

😉 just kidding. Tech writer heart attack averted. Have a chocolate!

Space jumping in a wiki documentation theme

A couple of weeks ago, I wrote about the new Documentation theme for Confluence wiki. There’s a bit I didn’t write about — something we technical writers requested specifically. It’s called “space jumping” and it’s just as awesome as its namesake. 😉

It’s a cold and wet Christmas long weekend, so I’ve decided to write a blog post about wikis instead of venturing outside:

Space jumping in a wiki 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. It’s done via the {spacejump} macro that is part of the new Documentation theme.

Why would you need to space jump?

Apart from the sheer thrill of it, you mean? 😉

We use it to put a standard message at the top of our archive spaces, telling people that they’re reading an old version of the documentation and letting them jump quickly to the same page in the latest documentation.

The result looks like this:

Space jumping in wiki documentation theme

Here it is again, in text instead of an image:

This documentation relates to an earlier version of Crowd.
View this page in the current documentation or visit the current documentation home.

And here’s the full screen (click the image to expand it):

Space jumping in wiki documentation theme

If someone clicks the link on “View this page in the current documentation”, they are taken to the latest version of the page:

Space jumping in wiki documentation theme

Here’s a link to the archive page in our documentation, so you can see the space jump in action.

How did we do that?

We’ve put the {spacejump} macro into the theme configuration. Here’s what our wiki markup looks like:

{note:icon=false}*This documentation relates to an earlier version of Crowd.*
View {spacejump:CROWD|alias=this page in the current documentation} or visit the [current documentation home|CROWD:].{note}

The format of the macro is:

{spacejump:SPACEKEY|alias=TEXT}

The ‘SPACEKEY’ parameter is required. Replace ‘SPACEKEY’ with the key of the space you want to jump to.

The ‘alias=TEXT’ parameter is optional. If you use it, replace ‘TEXT’ with the text you want hyperlinked. If you omit the parameter, Confluence will display the page name.

The macro is part of the Documentation theme, so if you have installed the theme then you can use the macro. We’ve used it in the theme configuration, but you can also use the macro on a normal wiki page.

Here’s a screenshot showing our full theme configuration for the archive space (click the image to expand it):

Space jumping in wiki documentation theme

What happens if the page does not exist in the target space?

For the space jump to work, the target space must contain a page with the same name as the page that renders the {spacejump} macro. If the target space does not contain such a page, you will see a broken link. Confluence handles this in its usual manner: the link is coloured red, and if you click it then Confluence offers to create the page for you.

In our particular use case a missing page is not very likely, because we seldom delete pages and our link points to the latest documentation space.

There’s probably a better way of handling unmatched pages. Maybe this is a chance for someone to raise an improvement request in the issue tracker for Jens’s Documentation theme! 😉

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. 🙂


%d bloggers like this: