This documentation relates to an earlier version of Confluence.
View this page in the current documentation or visit the current documentation home.

Skip to end of metadata
Go to start of metadata

Confluence's look and feel can be modified by editing the 'decorator' (layout) files. Modifying these files allows you to change the look and feel of:

  • The Confluence site as a whole, which includes all spaces within the Confluence site.
  • An individual space within the Confluence site.

This page tells you how to customise the layout files for your Confluence site as a whole. These customisations:

  • Modify the default 'decorator' files of each space in your site
  • Are reflected in every space unless the space's own equivalent layout files have been customised.

(info) You require System Administrator permissions to perform these customisations.

You can also customise the layout files for a given space only. For more information, refer to Customising Layouts for a Space.

(info) Space layout file customisations override the equivalent site layout file customisations.

 

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

Icon

If you modify the look and feel of Confluence by following these instructions, you will need to update your customisations when upgrading Confluence. The more dramatic the customisations are, the harder it will be to reapply your changes when upgrading. Please take this into account before proceeding with your customisation. For more information on updating your customisations, please refer to Upgrading Custom Layouts.

Confluence is built on top of the open source SiteMesh library, a web-page layout system. Read more on the SiteMesh website. To edit the layout of Confluence, you will need to modify these decorator files. A decorator file is a .vmd file and is written in a very simple programming language called Velocity. You can learn more from the Velocity User Guide.

Once you are familiar with Velocity, you can edit the decorator files to personalise the appearance of Confluence.

The decorator files are grouped into:

  • Site layouts : These are used to define the controls that surround each page in the site. For example, the header and the footer.
  • Content layouts : These control the appearance of content such as pages and blog posts: they don't change the way the pages themselves are displayed, but allow you to alter the way the surrounding comments or attachments are displayed.
  • Export Layouts: These control the appearance of spaces and pages when they are exported to HTML. If you are using Confluence to generate a static website, for example, you will need to modify these layouts.

Editing a site decorator file

  1. Go to the Confluence 'Administration Console':

    • Choose Browse > Confluence Admin. The 'Administrator Access' login screen will be displayed.
    • Enter your password and click Confirm. You will be temporarily logged into a secure session to access the 'Administration Console'.
  2. Select 'Layouts' under 'Look and Feel' in the left-hand navigation panel. The decorators are grouped under Site, Content and Exportlayouts.
    • Click 'View Default' to view the vmd file.
    • Click 'Create Custom' to edit the default vmd file. This will open up the vmd file in edit mode.
  3. Make changes and click 'Update'.

(info) If something goes wrong : Click 'Reset Default' to revert to the original layouts.

Using Velocity macros

When editing Custom Decorator Templates, there are a number of macros available to define complex or variable parts of the page such as menus and breadcrumbs. You may insert these macros anywhere in your templates. More information on Working With Decorator Macros.

For advanced users

The velocity directory is at the front of Confluence's velocity template search path. As such, you can override any of Confluence's velocity templates by placing an identically named file in the right place. While we don't recommend you do this unless you know exactly what you're doing, it does give you complete control over the look of every aspect of Confluence. It also means that you can edit your templates in a text-editor if you wish, rather than through the web interface.

Caching

Icon

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.

In Confluence 2.6 and later, some Velocity files are located inside the Confluence JAR file that can be found at confluence/WEB-INF/lib/confluence-x.x.x.jar. To override files inside this JAR (which you can open with any ZIP tool like WinZip or 7-Zip), put your customised file in the same directory structure under confluence/WEB-INF/classes/.

For example, the file templates/macros/alphaindex.vm inside confluence.jar can be replace by putting your custom file in WEB-INF/classes/templates/macros/alphaindex.vm. You do not need to modify the file inside the JAR.

See also Editing Files within JAR Archives.

RELATED TOPICS

Velocity Template Overview
Basic Introduction to Velocity