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!

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 27 March 2010, in atlassian, Confluence, technical writing, wiki and tagged , , , , , . Bookmark the permalink. 8 Comments.

  1. Sarah,
    I almost contacted Support last week because I had accidentally clicked the sidebar icon and the left-hand navigation pane disappeared. Then I found this on your blog. Thank you!!!

    Gina

    • LOL Gina! It happens to us all the time too. One of the best times is during a presentation: someone clicks the icon to get a wide screen, then the next speaker up is totally befuddled.😉

    • FYI: ePublisher 2010.1 was released on April 15, 2010. It includes an option to deploy pages under an existing Confluence page. So, you can now directly deploy your pages underneath your Home page and all will play nice with the documentation theme.

  2. Michael Kronenberg

    Hi Sarah,

    I’m using WebWorks to convert a very large book to Confluence output. I’d like to use the navigation sidebar, but a bunch of WW-generated pages–CSS, graphics, etc–are being deployed to the same path as the content pages, which obviously should *not* appear in the navigation bar. Is there some magic that would allow me to selectively suppress display of certain pages? Or is there something on the WebWorks side that I can do to redirect the deployment path?

    • Hallo Michael

      There are a few things you can do. The key thing is that, by default in the Confluence Documentation theme, the table of contents in the left-hand navigation bar will display all pages that are children of the space home page. It will “ignore” pages that are above or at the same level as the home page, in the space hierarchy of pages.

      Here are some tips that will help you to make use of this key fact. I’m hoping that one of them, or a combination of them, will help you solve the problem.

      In ePublisher (version 2010.1 and later), you can specify the Confluence page which will be the parent of the pages about to be imported.

      In Confluence, you can change the default home page of the space. Go to Space Admin and select ‘Edit Space Details’.

      It’s possible that you don’t want to change the space home page. So here’s another option. When using the Documentation theme, by default it will include the page tree and will show all pages below the space home page. If you like, you can change this behaviour by editing the configuration for the Documentation theme. The Confluence docs explain how:
      http://confluence.atlassian.com/display/DOC/Configuring+the+Documentation+Theme

      For example, you might want to deselect the “Page Tree” check box, to turn off the default page tree. Then you could use wiki markup to insert your own page tree, using the {pagetree} macro. This is the same macro that the theme uses. If you code it yourself, you can set different parameters, including the “root” i.e. the parent page for the tree. Here are the docs on the macro:
      http://confluence.atlassian.com/display/DOC/Pagetree+Macro

      Also in Confluence, you can drag and drop your pages into different locations in the space. So, if you want to “hide” pages from the left-hand nav bar, all you need to do is to put them “above” the parent page that the {pagetree} macro is using. So by default, you would put the pages above or at the same level as the space home page. You can drag and drop pages in the “Pages” section of the space “Browse” screen.

      There’s a bit more discussion about these aspects on this blog post, including some comments from Ben Allums of WebWorks:
      https://ffeathers.wordpress.com/2009/10/04/epublisher-for-converting-documents-to-confluence-wiki

      I hope that helps!
      Cheers
      Sarah

  3. Hello Sarah,

    You will be “pleased” to know that this is still an issue in Confluence 4.x. I exported/imported a space and had no left-hand navigation. And in checking, saw that the Velocity helper was disabled.I guess this is an indication of code stability?😉

    Thanks for posting!
    Bill

Leave a Reply

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

WordPress.com Logo

You are commenting using your WordPress.com 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 )

Google+ photo

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

Connecting to %s

%d bloggers like this: