Switch to the Default Theme

If you use the Documentation theme in your spaces, it's time to consider switching to the Confluence default theme.

A growing number of great features (such as JIRA links button, space shortcuts and sticky table headers) are not available in the Documentation theme, and we plan to retire this theme altogether in the near future. 

This page will show you how to turn on the default theme, and keep any existing header, footer or sidebar content.

Here's an example of the documentation theme, and default theme with the same custom content side by side:

On this page:

Understanding global look and feel

Before you start, it's important to understand the idea of "global look and feel".  Confluence allows you to apply most themes to an individual space, or to the whole site. When a space says it is using the 'global look and feel' it means it is using whichever theme has been applied for the whole site, and inheriting any customisations from the site level.

The Confluence default theme, however, can only be applied to a space if it is currently applied to the entire site (it must be the current global look and feel).

Switch your space to the default theme

To turn on the default theme and keep any existing header, footer or custom sidebar content:

  1. Go to Browse > Space Admin > Theme and then Configure theme
  2. Copy the wiki markup from the Navigation, Header and Footer fields to somewhere safe (like a document or text file) then Cancel.
    (If these fields are empty, you can go straight to the next step). 
  3. Select Global look and feel (that's the default theme) and choose Confirm.



    (If Global Look and Feel is already listed as your current theme you'll need to follow the steps below to change your Site theme first).
  4. The default theme is now enabled - you'll notice the space admin options have moved.
    Choose the Header, Footer and Sidebar tab.

     
     
  5. Paste the wiki markup for your custom sidebar content (navigation), header and footer into the fields provided then Save
  6. Use the space name link in the sidebar to get to the space homepage and check the appearance of your space. 
     
     

The default theme includes some extras in the sidebar, such as shortcuts and index pages for blogs and blueprints. Your custom content will appear between the shortcuts and page tree.

To choose what you'd like to show or hide:

  1. Go to Space Tools (at the bottom of the sidebar) and select Configure Sidebar.
  2. Use the  and  icons to show and hide each section.
  3. This is where you can change the site logo too. 

You can't hide the space name, logo or page tree.

Make the default theme available across the whole site

If the Documentation theme is enabled for the entire site, you won't see an option to switch to the default theme in each space. This means that before you can switch each space over to the default theme, you'll need to make it available for the whole site. 

To make the default theme available across your whole site:

  1. Go to  > General ConfigurationThemes
  2. Choose Configure theme beside the Documentation theme
  3. Copy any wiki markup from your header, footer and sidebar fields to somewhere safe (like a document or text file) then Cancel.
    (If these fields are empty, the Documentation theme has not been customised for the entire site)
  4. Select the Default theme and choose Confirm.
    The default theme is now the global look and feel. If you did not need to copy over any wiki markup, the process is now complete.  
  5. If you have wiki markup to migrate, go to  > General Configuration > Sidebar, header and footer
  6. Paste the wiki markup for your custom sidebar content (navigation), header and footer into the fields provided then Save

All new spaces will now be created with the default theme.

The impact on existing spaces depends on how the theme is applied:

  • All spaces that used the Documentation theme because it was the global look and feel will now use the default theme. You don't need to do anything.
  • All spaces that have the Documentation theme explicitly applied (for example to enable different wiki markup in the sidebar, header or footer) the documentation theme will still be applied, and you'll need to migrate each one separately.

Hints and tips for the sidebar

Here's a few hints and tips for making your sidebar migration as easy as possible.

Do you need to use wiki markup?

If the wiki markup in the Documentation theme for your space was simple, for example just adding a page tree and a couple of links to useful spaces or external sites, chances are you don't need to continue to customise the sidebar at all. The default theme comes with a page tree option, and you can add links to pages, spaces or websites. These space shortcuts are much easier to keep up to date (and are safe from page renames).

Are you using space CSS to style the theme?

If you're overriding the space CSS to change the appearance of the doc theme sidebar, you'll probably need to make some changes to your CSS, as some class and ID names are different between the two themes.

For example, instead of specifying #splitter-sidebar, you'll need to use .acs-side-bar.

 

Edit the header, footer or custom sidebar content

You can update the wiki markup for the sidebar, header and footer at any time.  Go to Space Tools > Look and Feel > Sidebar, Header and Footer

These fields use wiki markup, check our guide to wiki markup for help, or check out some common customisations below. 

  Add a search field to your sidebar...

To add a search field to the sidebar:

  1. Go to Space Tools > Look and Feel > Sidebar, Header and Footer
  2. In the Sidebar field add the wiki markup for either the Livesearch or Page Tree Search macros

    {livesearch}
    {pagetreesearch}
  3. The search field will appear above the page tree.
  Add a panel with some content...

To add a panel with some custom content to the sidebar:

  1. Go to Space Tools > Look and Feel > Sidebar, Header and Footer
  2. In the Sidebar field add the wiki markup for the Panel Macro then add some text:

    {panel}This is some custom content to appear in the sidebar{panel}
  3. Your content will appear above the page tree.

Documentation theme features that aren't available in the default theme

Not all documentation theme features are available in the default theme.

Limit search results to the current space

We've decided not to add the ability to restrict the Confluence search on the header to a single space for now. You will still be able to add the Live Search or Page Tree Search macros to the sidebar or homepage of your space, and set these macros to only return results from the current space.

Space jump macro

This macro is part of the documentation theme. It is still available for now, but is likely to be removed when we remove the Documentation theme. 

Child pages below the page content

In the Documentation theme, children of the current page are listed below the page content. This is not available in the default theme, however you could choose to add a Children Display Macro to the footer in the default theme.  

View pages alphabetically

In the Documentation theme you could choose to view all pages in a site alphabetically. This isn't available in the default theme.  

 

Troubleshooting

Find out which spaces are using the Documentation theme

There's no simple way to see a list of spaces using the Documentation theme in Confluence itself, however if you have a very large site, your Confluence Administrator can use the following query to get a list of spaces directly from the database.

SELECT *
FROM BANDANA B, SPACES S
WHERE B.BANDANAKEY='atlassian.confluence.theme.settings'
AND S.SPACEKEY=B.BANDANACONTEXT
AND B.BANDANAVALUE LIKE ('%documentation%')
ORDER BY S.SPACENAME;

This query will only find spaces that are explicitly using the documentation theme. It doesn't include spaces using the global look and feel (these spaces automatically change when you change the Site Theme, you wont need to change the theme space by space).

Check for layout changes

If the underlying layout templates for your spaces have been customised, you may find that your space looks strange or broken when you apply the default theme.

If this happens, you can reset the templates back to the default. You'll need to be a Site Administrator to do this.

  1. Switch back to the Documentation theme temporarily.
    (If you're unable to use the space navigation, use this URL, replacing YOURSPACEKEY with the space key for the space.

    http://<yoursite>/spaces/choosetheme.action?key=YOURSPACEKEY
  2. Go to Browse > Administration > Layouts or use the following link if you're unable to get there via the space navigation.

    http://<yoursite>/spaces/listdecorators.action?key=YOURSPACEKEY
  3. Choose Reset Default next to any template that have been customised.
  4. Return to the Themes page and try applying the default theme again.

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