This page last changed on May 15, 2008 by edawson.

You can customise the layout of your Confluence instance by editing the 'decorators' that define the look and feel of the site.

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. Learn more about Velocity. Once you become familiar with Velocity, you can edit the decorator files to personalise the appearance of Confluence.

You need to have System Administrator permissions in order to perform this function.

  • You can customise the layouts for a particular space or for the whole site. This page tells you how to customise layouts for the site as a whole. To customise the layouts for a space, use the 'Layout' menu on the 'Space Admin' page.
  • When you upgrade Confluence, you must reapply your custom layouts to the newly installed default layouts.

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 news items: 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.

To edit a site decorator file,

  1. Go to the 'Administration Console' view. To do this:

    • Go to a page in the space and choose 'Administration' from the 'User' menu, which is labelled with your Confluence username. The 'Administration Console' view will open.
  2. Select 'Layouts' under 'Look and Feel' in the left-hand navigation panel. The decorators are grouped under Site, Content and Group layouts.
    • 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'.

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.

WARNING
  1. 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.
  2. Because we only officially support the modification of the three global decorator files, other 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.
Change in Confluence 2.6.0

Some of the Velocity template files (files whose names end in .vm) were moved inside the main confluence-<version>.jar file with the release of Confluence 2.6.0 (i.e. $CONFLUENCE_INSTALL/confluence/WEB-INF/lib/confluence-2.6.jar in version 2.6). If you are unfamiliar with editing the contents of a .jar file, you may find these instructions useful. This is mostly relevant to those wishing to customise email or export templates.
Alternatively Java Servlet Technology allows you to use an unpacked version of the desired file in the WEB_INF/classes directory. Make sure you reproduce the exact directory (package) structure.


RELATED TOPICS
Creating a Theme Plugin
Customising Colour Schemes
Customising Layouts
Customising Look and Feel Overview
Global Templates

Velocity Template Overview
Basic Introduction to Velocity

Document generated by Confluence on Jun 24, 2008 18:01