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

Saturday, 27 March 2010 05:00

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?

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 ??? macro to produce the table of contents on the left. When you use the ??? 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!
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?

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.