Configure the Documentation Theme

The Documentation theme is going away in Confluence 6.0.
Read more about this change. 

The Documentation theme is designed for spaces containing technical documentation, but you may find it useful for other types of structured content. It provides a table of contents for your space, a configurable header and footer, and text styles suited to documentation. (See features below.)

Quick guide to applying and customising the Documentation theme:

  • Go to the space and choose Space tools > Look and Feel from the bottom of the sidebar
  • Choose Themes.
  • Select Documentation Theme and choose Confirm.
  • If you want to customise the theme, choose Configure theme.
    • Select or deselect the default page tree.
    • Select or deselect the space-restricted search.
    • Enter the text and wiki markup for your custom left-hand panel header and footer.
    • Choose Save.

The rest of this page gives more details of the above procedure.

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. Go to the space and choose Space tools > Look and Feel from the bottom of the sidebar
    You'll need Space Admin permissions to do this. 
  2. Choose Themes and select a theme option
  3. Choose Confirm

    Screenshot: Applying a theme

If your space is using the Documentation theme:

  1. Choose Browse > Space Admin from the header

    Note: The Space Admin option appears only if you have space admin permissions, or if you're part of the 'confluence-administrators' group.

  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. Choose Browse > Space Admin from the header

    Note: The Space Admin option appears only if you have space admin permissions, or if you're part of the 'confluence-administrators' group.

  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 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.
    (info) 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

Here's 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 The Documentation Theme.

 

Hints and tips

Below are some hints that you may find useful when using the Documentation theme.
Where can I see a working example of the Documentation theme?

The Confluence documentation uses the Documentation theme. If you are reading this documentation online on the Atlassian documentation wiki, you are seeing a working version of the Documentation theme.

Which pages will appear in the Documentation theme's table of contents?

The theme constructs the page tree in the left-hand panel from all pages that are child pages of the space’s home page. Each space has a single page designated as the 'Home' page. You can specify the home page in the space administration section.

Help, my pages do not appear in the Documentation theme table of contents

Cause 1: Your pages are not under the space's home page. The most probable reason why your pages do not appear in the page tree in the left-hand panel is this: The theme constructs that table of contents from all pages that are child pages of the space’s home page. If your pages are above the home page in the page tree, they will not appear in the left-hand panel.

There are two ways to fix the problem:

  • You can change the designated space home page in the space administration section.
  • Or you can drag and drop all your pages to make them children of the current home page. You can drag and drop pages in the 'Pages' section of the space 'Browse' screen. See Move and Reorder Pages.

Cause 2: Problem with upgrade from Confluence 3.1, with Documentation theme as plugin, to Confluence 3.2 or later with Documentation theme bundled. If your existing Confluence installation already has the Documentation theme plugin installed, you may find that after upgrading to Confluence 3.2 the left-hand navigation bar is empty in the spaces that use the theme. The fix is to enable all modules of the Documentation theme plugin. See the knowledge base article.

Help, my left-hand panel has disappeared

If your entire left-hand panel has disappeared when using the Documentation theme, this is probably because you have clicked the sidebar icon at top right, next to the search box. Click the icon again to restore the panel.

Can I change the default width of the left-hand navigation panel?

The Confluence user interface does not offer a way to change the default width of the left-hand navigation panel supplied by the Documentation theme. Users can change the width by dragging the middle bar, but the default width is not configurable. This post on Atlassian Answers gives a way to do it with CSS: Documentation Theme - Default Width (in px) of left panel.

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.

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;
}

To edit a space's CSS style sheets:
  1. Go to the space and choose Space tools > Look and Feel from the bottom of the sidebar
  2. Choose Stylesheet then Edit.
  3. Paste your custom CSS into the text field.
  4. Save your changes. The new CSS will be visible on all content pages in the space.

If your space uses the Documentation theme:

  1. Choose Browse > Space Admin from the header

    Note: The Space Admin option appears only if you have space admin permissions, or if you're part of the 'confluence-administrators' group.

  2. Click Stylesheet in the left-hand panel under the heading 'Look and Feel'.
  3. Choose  Edit.
  4. Paste your custom CSS into the text field.
  5. Save your changes. The new CSS will be visible on all content pages in the space.

Note: By default, only system administrators can edit the CSS for a space or for the site. To allow any user with Space Admin permissions to edit the CSS for a space, go to  > General Configuration > Security Configuration and select  Custom Stylesheets for Spaces.

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: CONF-25923 - Provide option to hide the left-hand panel entirely in the Documentation theme Resolved 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

  • The Confluence default theme supplies a sidebar, which is different to the left-hand panel in the Documentation theme. For information about the sidebar, see Configure the Sidebar.
  • The Documentation theme supplies a Browse menu in the Confluence header, which gives access to the space administration and advanced options.

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport