Customize Space Layouts

On this page

Still need help?

The Atlassian Community is here for you.

Ask the community

You can modify Confluence's look and feel by editing the layout files. This page tells you how to customize the layout files for a space. You'll need the system administrator global permission plus space administrator permission for that space.

People with system administrator permissions can also customize the layout of the entire Confluence site. For more information, see Customizing Site and Space Layouts. Site layout customizations modify the default layout of all spaces in the Confluence site.

Any space layout customizations will override the equivalent site customizations.

If you modify the look and feel of Confluence by following these instructions, you'll need to update your customizations when you upgrade Confluence. The more dramatic the customizations are, the harder it'll be to reapply your changes when upgrading. Please take this into account before proceeding with any customizations.

For more information on updating your customizations, please refer to Upgrading Customized Site and Space Layouts .

Confluence is built on top of the Open Source SiteMesh library, a web-page layout system that provides a consistent look and feel across a site. SiteMesh works through 'decorators' that define a page's layout and structure. 

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 personalize the appearance of Confluence.

The decorator files in Confluence are grouped into the following categories:

  • Site layouts: These are used to define the controls that surround each page in the site. For example, if you want to make changes to the header and the footer, you will need to modify these layouts.
  • Content layouts: These control the appearance of content such as pages and blog posts. They do not change the way the pages themselves are displayed, but they allow you to alter the way the surrounding comments or attachments are shown.
  • 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.

Learn more about using decorators.

To edit a decorator file:

  1. Go to the space and choose Space tools > Look and Feel from the bottom of the sidebar

  2. Choose Layout  (Layout is displayed only if you are a Confluence system administrator.)
    You'll see a list of the layouts for the space
  3. Click Create Custom to edit the default vmd file
    This will open up the vmd file in edit mode. If you only want to view the vmd file, click View Default.
  4. Make any changes and click Update

Last modified on Mar 22, 2022

Was this helpful?

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