Screenshot: The Documentation theme showing the space sidebar replaced by a navigation sidebar.

Applying the Documentation theme to your space

Follow the steps below to apply the Documentation theme to your space. All pages in the space will start using the theme immediately.

To apply a theme to a space:

1. 
   
2. Choose Themes and select a theme option
3. Choose Confirm
   
   Screenshot: Applying a theme
   

If your space is using the Documentation theme:

1. 
2. Choose Themes from the space administration options
3. Select a theme option
4. Choose Confirm

Applying the Documentation theme to your site

If you have site administrator permissions, you can apply the theme at site level. It will then be the default theme for all spaces in the site. See the administrator's guide to applying a theme.

Customising the Documentation theme

The theme works well without any customisation. If necessary, you can restrict the search to just one space, change the content of the left-hand navigation panel and add your own header and footer. The following instructions assume you have already applied the Documentation theme.

To customise the Documentation theme:

1. 
2. Choose Themes in the left-hand panel under the heading 'Look and Feel'.
3. Choose Configure theme in the yellow area of the 'Current Theme' section at the top of the page. See screenshot below. The 'Documentation Theme Configuration' screen appears. See screenshot below.
4. Select or deselect the Page Tree check box. This determines whether your space will display the default search box and table of contents (page tree) in the left-hand panel.
5. Select or deselect the Limit search results to the current space check box.
   
   • If you select the check box:
     
     • The Confluence search will look for matches only in the current space by default. Users can override this restriction when entering their search term. See Using the Documentation Theme.
     • The default page tree in the left-hand panel will not include a search box.
   • If you do not select the check box:
     
     • The Confluence search will look for matches in the entire Confluence site. This is the default behaviour for other themes too.
     • The default page tree in the left-hand panel will include a search box, which restricts search results to the current space.
6. Enter text, images, macros and other wiki markup into any or all of the three text boxes.
   You can use the Include or Excerpt Include to include re-usable content into your footer. See hint below.
   
   • 'Navigation' – This text box contains content for the left-hand panel.
     
     • If the Page Tree check box is selected, the navigation panel contains the default search box and page tree. Any content you enter into the 'Navigation' text box will appear above the page tree and search box.
     • You can include your own content underneath the page tree as well as above. See hint below. In summary: Deselect the Page Tree check box. Insert your own page tree using the Pagetree macro, then add your own content under the macro.
   • 'Header' – This text box contains content for a page header that will appear above the page title on all pages in the space. See example screenshot below.
   • 'Footer' – This text box contains content for a page footer that will appear after the comments and above the site footer, on all pages in the space. See example screenshot below.
7. Choose Save.

Screenshot: The 'Configure theme' option

Screenshot: Customising the Documentation theme

Customising the theme at site level

If you have site administrator permissions, you can apply and customise the theme at site level. The customisation options are the same as the space level options, as described above.

Features of the Documentation theme

Screenshot: A customised header, footer and left-hand panel

The above screenshot shows a wiki space with a customised left-hand panel, header and footer.

Here is a summary of the features that the Documentation theme provides:

• By default, the left-hand panel contains a search box and a table of contents (page tree) showing all the pages in your space. Specifically, it shows the pages that are children of the space's home page.
• The left-hand panel is fully customisable. You can choose to include or exclude the search box and page tree. You can enter your own text, images and wiki markup.
• People viewing the page can drag the thick bar between the left-hand panel and the content, to increase or decrease the width of the panel. They can also remove the panel altogether, by clicking the sidebar icon at top right, next to the search box.
• The left-hand and right-hand panels scroll independently of each other.
• 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.
• Because the left-hand panel is part of the theme, it will be upgraded whenever Confluence is upgraded. There is no need to remove and then re-apply your customisations on each upgrade, as you would do if you added your own left-hand navigation bar.
• The theme also provides a customisable header and footer, which will appear at the top and bottom of every page.
• The text and heading styles are designed to enhance the content typically found in a documentation space.
• You can use the Space Jump macro to 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.
• You can limit the Confluence search results to the current space. If you choose this option, the Confluence search will look for matches only in the current space by default. Users can override the restriction. See Using the Documentation Theme.

Hints and tips

Hiding pages from the left-hand table of contents

You can 'hide' pages by putting them at the same level as or higher than the space home page.

Each space has a single page designated as the 'Home' page. You can specify the home page in the space administration section.

The theme constructs the page tree in the left-hand panel from all pages that are child pages of the space’s home page.

If your documentation pages are at the same level as the space home page, they will not appear in the left-hand navigation bar. So you can 'hide' pages by putting them at the same level as or higher than the space home page. The pages 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.

More detail: The theme uses the Pagetree macro to produce the table of contents. When entering the Pagetree macro, you can choose the top page in the page tree. The Documentation theme chooses the space home page as the top page.

Using reusable content in your header, footer or sidebar

You can use any text or wiki markup in your theme header, footer or left-hand panel. One useful hint is to use the Include or Excerpt Include to include re-usable content into your footer.

The screenshot above shows the theme customisation options, with examples of the macros used to include content from other pages. And the example screenshot also above shows the resulting header, footer and left-hand panel.

Adding content below the page tree in your sidebar

If you want to include your own content underneath the page tree, you can deselect the 'Page Tree' check box, add your own page tree using the Pagetree macro in the 'Navigation' text box, and then add your own content under the macro.

The screenshot above shows the theme customisation options, with the default page tree deselected and a custom page tree inserted, along with additional content in the left-hand panel. The example screenshot also above shows the resulting left-hand panel.

Adding an expanding All Versions section to the sidebar

If you want to include a an expanding list of links to other spaces, as we have included in this space (see 'Docs for all Confluence releases' in the sidebar), you can use an Expand Macro and an Include Page Macro in the 'Navigation' text box.   For example:

*[Docs for all Confluence releases|_Latest Versions of Confluence Documentation]*
{expand:Choose a version...}
{include:_Latest Versions of Confluence Documentation}
{expand}

If you would like this to display below the page tree, follow the steps above.

Adding underlines to your links

By default, the Documentation theme does not underline hyperlinks. If you prefer to have your links underlined, you can edit the CSS stylesheet for your space and add the following CSS code:

.wiki-content a:link, .wiki-content a:visited, .wiki-content a:active {
  text-decoration: underline;
}

Jumping to the same page in another space

The {spacejump} macro is provided along with the Documentation theme. You can use space jumping to 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. When a reader is viewing a page and chooses the link provided by the macro, they will go to a page with the same name, but in the space specified in the macro. See more about the Space Jump macro.

Hiding the left-hand panel completely

It's not possible to remove the left-hand panel entirely, using the user interface supplied by the theme. There is an improvement request here: If you like, you can comment on and/or vote for that request. In the meantime, Atlassian Answers is a good place to ask the question and see if other people can help you with custom code to remove the panel.

Notes