Customising Site and Space Layouts

You can modify Confluence's look and feel 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.

You need System Administrator permissions to perform these customisations.

You can also customise the layout files for a given space. For more information, refer to Customise Space Layouts. Space layout customisations override the equivalent site customisations.

 Note: 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 Customised Site and Space 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 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 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, the header and the footer.
  • 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 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. Choose the cog icon , then choose General Configuration under Confluence Administration
  2. Select Layouts under Look and Feel in the left-hand navigation panel.
    • Click View Default to view the .vmd file.
    • Click Create Custom to edit the default .vmd file. This will open 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.

Advanced customisations

Overriding Velocity templates

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.


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/, or restart the server to make your changes visible.

Location of Velocity files

You will find the Velocity files in your Confluence installation directory. The primary Velocity files are located in the <CONFLUENCE-INSTALLATION>\confluence\decorators directory. For example, you will find the following files in that directory: main.vmd, space.vmd, form-aui.vmd, global.vmd, and more.

Finding the layout via the URL

If the layout has changed so extensively as to not be visible, you can browse to the URL directly:

Substitute the base URL and the appropriate .vmd file.

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

19 Archived comments

  1. User avatar

    Matt Boesch

    I do not see a file in the Confluence directories.  I was able to edit a velocity template (footer.vm) without having to do a restart.  Is caching turned off by default in Confluence?  I do see the file in the /WEB-INF/classes of JIRA, but not Confluence.

    30 Jul 2009
    1. User avatar

      Sashidaran Jayaraman [Atlassian]

      Hi Matt,

      The is bundled inside the confluence-X.X.X.jar file where X.X.X is the version number. This jar file is located at <confluence-install>/WEB-INF/lib/. Most of the time, you can freely edit the velocity file without having to restart the Confluence instance if you force refresh the page. As for your third question, cache is turned on by default in Confluence. In order to turn it off, kindly refer to this documentation


      03 Aug 2009
      1. User avatar

        David Vonka

        in cfl 4.3-m11, the file is (again ?) in WEB-INF/classes

        13 Jun 2012
  2. User avatar


    all I get after clicking on "layout" (step 2) is this:

    You can not customise the site look and feel while a theme is active. You must first disable currently configured theme.

    but no mater which theme is enabled, I still get the error message...

    10 Dec 2009
    1. User avatar

      Sashidaran Jayaraman [Atlassian]


      I believe you are encountering the issue described in our Knowledge Base entry. Kindly follow the resolution suggested in the KB and see if the problem is resolved. If problem persists, feel free to raise a support ticket to, so that your issue can be further investigated.


      31 Dec 2009
  3. User avatar

    Peter Binney

    This page is out of date or wrong (as, sadly, is so much of your customisation documentation).

    In 4.3 (at least), the master velocity files are in the installation's confluence/decorators folder.

    ie: main.vmd is there as a file (eg: in atlassian-confluence-4.3.3-war.tar.gz) and is not embedded in confluence-4.3.3/confluence/WEB-INF/lib/confluence-4.3.3.jar

    07 Dec 2012
    1. User avatar

      Sarah Maddox [Atlassian]

      Hallo Peter

      Thanks for pointing this out! I've fixed the page. You're right that much of the customisation documentation is out of date. Alas, it's due to chronic understaffing on the technical writing team. We're hiring though, and hope to fix that situation too.

      Cheers, Sarah

      08 Dec 2012
  4. User avatar


    I am a system administrator, but not a developer. In the previous versions, it was quite easy for us to update the global page header, body, and footer.  We clicked on customize theme > footer > and input the text.  Specifically, we needed a footer that has a confidential and proprietary statement. However, with the upgrade, all of this was lost and now I am quite confused as to how to reapply this statement as it is critical for us to have on EVERY page.  Our global headers and footers were all wiped out.

    How do I do this with these new layouts.  Again, I'm not a developer and don't have access to such resources without paying additional for the resources.  Please help!

    28 Jan 2013
    1. User avatar

      Sarah Maddox [Atlassian]

      Hallo there anonymous

      Please would you let us know which version of Confluence you're using – have you upgraded to the Beta version of Confluence 5.0 on a test site, or are you perhaps using a Confluence OnDemand site?

      It sounds as if you were using customisation of the header and footer via the Documentation theme – is that right? As far as I know, the customisations should still be possible, but I'll investigate when I know more about your environment.

      Cheers, Sarah

      28 Jan 2013
  5. User avatar


    Hi,  What is the process to accomplish a footer on all documents that says "Confidential and Proprietary" - we are on Wiki 4.3.1?   I just got this request today and it needs to be on every document global (Oline and Printed).  

    Thank you,


    13 Feb 2013
  6. User avatar


    Hi! I'm the admin and I do not have the option of Layouts under look and feel

    27 Apr 2013
  7. User avatar


    After upgrading, all our pages' bullets have been centered instead of left-justified.  When you edit a page, it looks left-justified, but when you save the page, all bullets become centered.  How do we fix this?

    19 Jul 2013
  8. User avatar

    Tiny Creative

    how do you change the vertical size of the Top bar menu? I looked at header.vm but could not discern where I can increase the pixel height of the bar.  

    05 Aug 2013
  9. User avatar



    I want to display the creator(author) information on the page when they are going to create the page.

    For this requirement which vm file i have to edit.

    Thank you,


    28 Aug 2013
  10. User avatar

    Matthew J. Horn

    The Sitemesh link on this page is broken.

    30 Dec 2013
  11. User avatar

    Matt K

    We have tried to customize our Velocity templates, mainly the search.vmd file under confluence/decorators but the changes never seem to take affect.  We have tried editing the file according to the Disable Velocity Caching documentation and restarting the server.  Still no results. 

    We are using Confluence 5.2.3. 

    Are the VM files cached or stored somewhere else?  Any other insight that other might be able to provide?

    07 Apr 2014
  12. User avatar

    Todd Todd

    I was so happy to find this page after hours of searching for instructions for modifying the global .css of Confluence 5.7. Alas, it appears that much of the basic information on this page is out-of-date despite being labeled as current. Similarly, the Global Stylesheet option, accessed in the "Look & Feel" section of main, left-hand menu, is a just an empty text field. So far I haven't been able to find an editable, current source for the global.css. These are just a couple of examples of the many dead ends encountered in trying to effect minor customizations to the UI.


    23 May 2015
    1. User avatar

      Giles Brunning [Atlassian Technical Writer]

      Hi Todd,

      Sorry to hear you didn't find what you're looking for. Regarding the global stylesheet: it's there for you to add any CSS customisations you'd like. You should be able to inspect any element on a Confluence page to find out its class or id, and reference that in the stylesheet. You don't need to edit the existing stylesheet; just add whatever overrides you need to.

      You can also add to the space stylesheet in the same way, if you'd like to make changes to a specific space.

      If you're looking to make specific changes and want to see if anyone else has already made those changes (or similar), answers can also be a great source of knowledge.

      25 May 2015
      1. User avatar

        Todd Todd

        Hi Giles, Thank you for the reply and for explaining that there is not supposed to be a global style sheet available from the Confluence admin console. I will take your advice and try the element inspection route. If successful, I'll post the steps involved for future explorers.

        25 May 2015
Powered by Confluence and Scroll Viewport