Documentation theme migration FAQ

Apply a Theme to a Space

On this page

Still need help?

The Atlassian Community is here for you.

Ask the community

As previously announced, the documentation theme is not available in Confluence 6.0. We know you'll have a lot of specific questions, so we've created this FAQ to help you prepare for upgrading to Confluence 6.0. 

If you have further questions, you can ask them at the bottom of the page and we'll do our best to provide an answer. 


What does the default theme look like?

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


  1. Documentation theme: with custom sidebar content.
  2. Default theme: with the same custom content in the sidebar.

How can I check if I am using the documentation theme in my space? 

The easiest way to check whether your space is using the documentation theme is to look for a Browse menu in the header, near the Create button.  (If you're using the default theme already, you'll see a Space Tools menu at the bottom of the sidebar instead.)

How can I check if the documentation theme is being used anywhere in my site?

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

What will happen to my theme customizations during the upgrade? 

During the upgrade we'll automatically turn on the default theme for any spaces that currently use the documentation theme. If you've customized the documentation theme (by adding wiki markup to the sidebar, header or footer) we'll take this wiki markup and drop it into the sidebar, header and footer in the default theme.  

The default theme adds some new sections to the sidebar, such as links to pages, blogs and space shortcuts.  You can choose to hide these - head to Space Tools > Configure Sidebar and use the  button to hide any items you don't want to see.

Will my space break after the upgrade?

This depends on the amount of customization you have. In most cases your space sidebar may look a little different but the changes shouldn't be dramatic.  

If you've used CSS to change the appearance of your space (either in the space stylesheet or by using the Adaptavist Content Formatting macros like  {style} and {div} in the sidebar, header, or footer of the documentation theme), you may need to make a few changes to some class names in your CSS to get your space looking right. For example, if you specified #splitter-sidebar in the doc theme, you'll need to use .acs-side-bar for the default theme. 

If you have customized default theme layouts through the Confluence UI, you may find that your space looks strange or broken when the default theme is re-applied to spaces previously using the documentation theme. 

If you experience problems, you'll need to reset the broken layouts. 
  

Reset customized layouts through the UI...

This method will only work if you have more than one theme available in your site. You'll need System Administrator global permission to do this.

  1. Switch to another 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. In the space administration options go to Layouts (if available) or use the following link, replacing  YOURSPACEKEY with the space key for the space.

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

Layouts can also be customized for the entire site - head to  > General Configuration > Layouts if you need to reset the layout for the entire site.

Remove customized layouts in the database...

If you're unable to reset the layouts via the Confluence UI, you can remove the affected layouts directly in the database. Be sure to take a full database backup before you try this.

First, use the following query to identify customized layouts:

Select *
FROM DECORATOR
ORDER BY SPACEKEY

Then, you can selectively remove records for spaces that are affected.

Can I add custom content to the sidebar, header and footer globally?

Yes. Head to  > General Configuration > Sidebar, Header and Footer.  All spaces that use the global look and feel will inherit your custom content.  Any custom content added to the sidebar, header and footer in a particular space will override any custom content added globally. 

Can I still use macros in my sidebar, header or footer?

Yes! If a macro worked correctly in the documentation theme it'll work in the default theme too. 

Where should I add custom content to the sidebar, header or footer?

You can add custom content to the sidebar, header and footer in each space individually (Space Tools > Look and Feel > Sidebar, Header and Footer) or globally ( > General Configuration > Sidebar, Header and Footer).

Confluence displays global custom content in all spaces, except where a space has its own custom content defined (space custom content overrides global custom content).  This behavior applies field by field, so a space can display a combination of custom content.  For example you could define the content of a footer globally, and content of a header in each space individually, or only in some spaces. 

How do I turn off the Pages and Blogs shortcuts at the top of the sidebar?

Go to Space Tools > Configure Sidebar and use the  icons to hide any items you don't want to see. 

Can I edit the default theme's sidebar globally?

No. You can add custom content to the sidebar globally, but showing and hiding sections of the sidebar, setting space logos, and adding shortcut links are done on a space by space basis. 

I want to see the page tree, not child pages. how do I do this?

Head to Space Tools > Configure Sidebar and select Page Tree in the navigation options.   The default for all new spaces is Page Tree.  

Where is Space Administration and Space Operations?

Instead of choosing between Space Operations and Space Administration, the documentation theme has a single Space Tools menu that lets you jump right to Permissions, Content Tools, Look and Feel, or Integrations.  


Here's a handy table of where to find everything in your new theme...
Old Space Operations locationNew Location in the sidebar
Browse > PagesPages on the sidebar or Space Tools > Reorder pages
Browse > BlogsBlogs on the sidebar
Browse > Labels
Click a label on any page, then use the menu to see all labels, popular labels or pages from other spaces
Browse > Space Operations > Space DetailsSpace Tools > Overview
Browse > Space Operations > Orphaned PagesSpace Tools > Content Tools > Orphaned Pages
Browse > Space Operations > Undefined PagesSpace Tools > Content Tools > Undefined Pages
Browse > Space Operations > AttachmentsSpace Tools > Content Tools > Attachments
Browse > Space Operations > PDF, HTML, XML ExportSpace Tools > Content Tools > Export
Browse > Space Operations > RSS FeedsSpace Tools > Content Tools > RSS Feeds
Browse > Space Operations > Watch this spacePages > Watch this space (or use the Watch button on any page)
Browse > Space Operations > Watch this blogBlogs > Watch this blog (or use the Watch button on any blog post)
Browse > Space Operations > Remove from My Spaces
Use the icon in the sidebar (or in the space directory)

Browse > Space Admin > Space Details

Space Tools > Overview
Browse > Space Admin > Space CategoriesSpace Tools > Overview
Browse > Space Admin > TemplatesSpace Tools > Content Tools > Templates
Browse > Space Admin > Delete SpaceSpace Tools > Overview > Delete Space
Browse > Space Admin > TrashSpace Tools > Content Tools > Trash
Browse > Space Admin > PermissionsSpace Tools > Permissions
Browse > Space Admin > Restricted PagesSpace Tools > Permissions > Restricted Pages
Browse > Space Admin > Application linksSpace Tools > Integrations > Application Links
Browse > Space Admin > ThemesSpace Tools > Look and Feel > Themes
Browse > Space Admin > Color SchemeSpace Tools > Look and Feel > Color Scheme
Browse > Space Admin > PDF LayoutSpace Tools > Look and Feel > PDF Layout
Browse > Space Admin > PDF StylesheetSpace Tools > Look and Feel > PDF Stylesheet
Browse > Space Admin > Change Space LogoSpace Tools > Configure Sidebar then choose the edit icon on the space logo
Browse > Space Admin > Hipchat IntegrationSpace Tools > Integrations > Hipchat

Do I have to use wiki markup in the sidebar, header, and footer?

Yes. Our main focus when adding this feature was to help people move from the documentation theme to the default theme with a minimum of effort. Keeping these fields as wiki markup means that your existing customizations can be pasted straight in. 

Can I hide or change the space logo appearance?

You can upload any image to use as your space logo, but you can't change how it appears in the sidebar (it's always round and always at the top). 

Can I hide the built in page tree and insert my own? 

Yes! If you want to have complete control over how the page tree appears in your sidebar you can hide the built in page tree, and then add a Page Tree macro {pagetree}  in the sidebar custom content. 

How can I make my page titles wrap in the sidebar?

Page titles do not wrap in the sidebar of the default theme (regardless of whether you're using the built in page tree or have added a {{pagetree}} macro as custom content). There's no way to change this.

Can I change the order in which things appear in the sidebar?

You can change the order of some items in the sidebar, such as the shortcuts, but the order of the sections themselves can't be changed. Anything that has a  icon can be moved. 

Custom content appears above the page tree.  You have the option to hide the built in page tree, and then add it back in the custom content area using wiki markup. This can be useful if you want more control over the order of the page tree and your custom content.  

Can I still use the space jump macro? 

No, the space jump macro was provided by the documentation theme and will not be available once the documentation theme is removed.   If you've used this macro on a page or in the header or footer of a space, it will show the following error after the upgrade  unknown macro: {spacejump}.  

To find out whether the Space Jump macro is used on any pages in your site, enter macroName:spacejump into the search bar.  All pages containing the macro will be returned (it won't search the sidebar, header or footer unfortunately). 

Why don't child pages appear below the page?  

The default theme does not list child pages below the sidebar, but you can achieve a similar result by adding a Children Display macro to the footer. 

Can I restrict search to just this space?

No, that is one of the features we removed with the documentation theme. 

One workaround is to add a Livesearch macro to the sidebar or space homepage. Use @self in the spaces parameter to restrict the search to the current space. 

How do I view the pages in my space alphabetically?

The default theme does not have an option to view all pages in your space alphabetically. 

What will happen if I import a space that uses the documentation theme?

You should have no problems importing the space, but it will have the default theme applied and any wiki markup customization in the theme will not be automatically migrated to the default theme. Before exporting the space you should copy the wiki markup contents of the sidebar, header, and footer fields and keep it so that you can add it back in manually after you've successfully imported your space. 

Last modified on Oct 11, 2021

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.