Documentation for Confluence 5.7.
Documentation for Confluence Cloud and earlier versions of Confluence is available too.

Skip to end of metadata
Go to start of metadata

As Confluence evolves, so do the default site and space layouts that drive the rendering of every page. As new functionality is added or current functionally is changed, the default layouts are modified to support these changes.

If you are using custom layouts based on defaults from a previous Confluence version, you run the risk of breaking functionality, or worse, missing out on great new features!

Take care on each new release of Confluence to reapply your changes to the new default templates.

To reapply your custom layouts, you need to:

  1. Obtain the source of your custom layouts from your current version of Confluence.
  2. Reapply your customisations to the new default layouts.
 

(warning) The information on this page does not apply to Confluence Cloud.

Step 1. Obtain your Custom Layouts

Ideally, you should keep a record of each customisation you have applied to each of your Confluence site or space layouts.

If not, you should be able to find your customisations using the following method. This method extracts all site- and space-level layouts from your Confluence site as a single output. From this output, you should be able to identify your customisations.

This method is handy to use if you have:

  • Many spaces with space layout customisations, or
  • Do not have an independent record of your site or space layout customisations.

Custom layouts are stored in the DECORATOR table within your Confluence database. You can SELECT for the source of the layout using SQL like this:

mysql> select SPACEKEY,DECORATORNAME,BODY from DECORATOR;
+----------+---------------------+------+
| SPACEKEY | DECORATORNAME       | BODY |
+----------+---------------------+------+
| NULL     | decorators/main.vmd | ...  |
+----------+---------------------+------+
1 row in set (0.03 sec)

This example was tested on MySQL, but should be applicable to all SQL databases.

Step 2. Reapply your Customisations

When you upgrade Confluence to another major release of Confluence, you will need to manually reapply any customisations you made to any site-wide or space-specific layouts. Unless otherwise stated, you should not need to reapply customisations after conducting a minor release upgrade of Confluence.

What are 'major' and 'minor' releases? Major release upgrades are ones where the 1st digit of Confluence's version number or the 1st digit after the 1st decimal place differ after the upgrade, for example, when upgrading from Confluence 3.0 to 3.1, or 2.8 to 3.0. Minor release upgrades are ones where the 1st digit of Confluence's version number and the 1st digit after the 1st decimal place remain the same after the upgrade, for example, when upgrading Confluence 3.0 to 3.0.1.

If you have made Confluence site-wide layout customisations:

  1. Choose the cog icon , then choose General Configuration under Confluence Administration
  2. Select Layouts in the left-hand navigation panel. The decorators are grouped under Site, Content and Export layouts.
  3. Ensure you have all your customisations available (preferably in a form which can be copied and pasted).
  4. Click Reset Default next to the layout whose customisations need to be reapplied.
  5. Click Create Custom next to the same layout and reapply your customisations (by copying and pasting them) into the appropriate locations within the new default layout.
  6. Click the Save button.
  7. Repeat this procedure from step 4 for each layout whose customisations need to be reapplied.

If you have made space-specific layout customisations:

  1. Go to the space and choose Space tools > Look and Feel from the bottom of the sidebar. 
  2. Choose Layout. The decorators are grouped under Site, Content and Export layouts.
  3. Ensure you have all your customisations available (preferably in a form which can be copied and pasted).
  4. Click Reset Default next to the layout whose customisations need to be reapplied.
  5. Click Create Custom next to the same layout and reapply your customisations (by copying and pasting them) into the appropriate locations within the new default layout.
  6. Click the Save button.
  7. Repeat this procedure from step 5 for each layout whose customisations need to be reapplied.

If your space is using the Documentation theme:

  1. Go to a page in the space.
  2. 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.

  3. Choose Layout from the left hand panel. 
  4. Follow the steps above.

Step 3. Test your Modifications Carefully

Changes may interact unpredictably with future versions of Confluence. When upgrading, you should always test your custom modifications thoroughly before deploying them on a live site. It's beyond the scope of Atlassian Support to test and deploy these changes.

Turning Off Caching

Velocity is configured to cache templates in memory. When you edit a page from within Confluence, it knows to reload that page from disk. If you are editing the pages on disk, you will either have to turn off Velocity's caching temporarily in WEB-INF/classes/velocity.properties, or restart the server to make your changes visible.

The velocity.properties file is available in the confluence-x.x.x.jar file, where x.x.x is the Confluence version number. The JAR file is located in the WEB-INF/lib directory. If you wish to make modification to the files in the JAR, we recommend the following steps:

  1. Stop Confluence.
  2. Make a backup copy of the JAR file.
  3. Un-jar the file
  4. Locate and edit the appropriate file that you wish to modify.
  5. Re-jar the confluence-x.x.x.jar file.
  6. Relocate the JAR file to the appropriate directory.
  7. Restart Confluence.
RELATED TOPICS

Customising Site and Space Layouts

 

3 Comments

  1. Hi,

    I made some tests on notpermitted.vm.

    I restarted Confluence but I can not see my changes (also deleting cache or changing browser).

    I made this: http://confluence.atlassian.com/display/DOC/How+to+Reset+a+Custom+Layout

    but nothing change

    I'm using the Adaptavist Theme builder and Confluence 3.5

    do you have any idea please ?

  2. Is there any where I can find layout code for Confluence? I need CSS code and HTML code. I would like to use some basic code to create my own layout.

     

    Thanks,

    Kat

    1. Hi Kathleen, There is some info about editing the decorator templates here  Customising Site and Space Layouts and here Custom Decorator Templates

      Beyond that, I'd recommend searching at Atlassian Answers as there might be others in the community who have customised the look and feel of their site and shared how they did it. 

      If you don't want to get stuck into the code, there are a number of add-ons that provide pretty sophisticated theming and styling for Confluence.