Documentation for Confluence 5.8 (Server).
Documentation for Confluence Cloud and earlier versions of Confluence is available too.

Skip to end of metadata
Go to start of metadata

You can modify Confluence's look and feel by editing the layout files. This page tells you how to customise the layout files for a space. You will require need space administrator permissions for that space.

If you're a Confluence system administrator, you can also customise the layout of your entire Confluence site. For more information, see Customising Site and Space Layouts. Site layout customisations modify the default layout of all spaces in the Confluence site.

Any space layout customisations will override the equivalent site customisations.

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

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 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 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, 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

You can't update the layout templates if your space is using the Documentation theme.

Screenshot : Edit Layouts Example



  1. Hi,

    I have modified a space layout to add page navigation sidebar, as suggested in a related thread. I would like to exempt or create an exception for some pages in my space from the custom layout where I do NOT want the sidebar, such as by using labels. For instance, the logic is "if current page has this label/attribute X, do not apply custom layout, else apply custom layout as specified." I'm having some trouble figuring out if there is a way to reference a page's labels in the layout code (I'm open to using something other than labels). Can you help, or have other suggestions for how I might do this?

    Thanks much!

    1. Hi Lindsay,

      Perhaps the following code will be helpful for you to achieve your requirements:

      The code above should be placed in the Page Layout which you can access from Dashboard > Administration > Look and Feel > Layouts > Create custom Page Layout. Feel free to change the label name (notree) to suit your needs.

      Hope this helps. Let me know if you have any difficulties in getting this done.


      1. JSashi,

        Thank you so much! This is exactly what I was looking for and it worked like a charm. I love how flexible and easy to apply it is with the labels.

        I really appreciate the help; you guys at Atlassian are the best.

        Best regards,


        1. Hi Lindsay,

          No worries, have a nice day.


      2. I'd like to put the labels into the keywords metatag for each page... this code snippet you provide seems to lead me to beleive it can be done, but I can't seem to get it to work...

        No where in my current custom layout for Main Layout is there a reference to a $helper object, but instead there is reference to $sitemeshPage..

        The Page Layout references $helper, but that's too late in the code, I really want to render a date, updatedate, and keywords metatag to improve the searchability of wiki content in our Enterprise Search engine.

        Essentially for each page render:

  2. i was trying to move elements from one decorator file to another. but ist didnt work.

    For example i want to move

    from main.vmd to page.vmd.

    any idea why?

  3. Anonymous


    The navigation bar in my pages differ from one page to another. I have sometimes at the top of the page and sometimes on the side.

    How can I make it all the same?

    Many thanks

  4. Hello, I want to create a custom layout for a space, but when I go into "Layouts" I get the message "You can not customise the site look and feel while a theme is active. You must first disable currently configured theme."

    How do I disable the current theme? If I go to "Themes" in Space Admin it shows me which theme is the current theme for the space, and it allows me to choose a different theme, but it doesn't let me deselect the current theme. Where do I go to do this?

    1. Anonymous

      We're having the same problem - very frustrating.  

      1. Hi,

        Unfortunately, the custom layout feature is currently supported only in the Confluence Default Theme. You need to set both your Space Theme and Global Theme to Confluence Default Theme in order to use the custom layout feature. For more information, check the following KB:

        Hope this helps.


  5. Anonymous

    Unable to customize the layout. Displays message: "You can not customise the site look and feel while a theme is active. You must first disable the currently configured theme." Is there something I need to do in the configuration first?

    1. This suggests the current theme set for the space does not support custom layouts. The only theme that currently support custom layouts (to my knowledge) is the Confluence Default Theme.

  6. Is there a list of what is NOT available or broken when trying to use Velocity syntax in the decorators? For example, I have not been able to use the #include or #parse directives, which should be very simple. Filed a bug, but figured I'd ask here, too. 


    Matthew Horn

  7. Hello, I am relatively new to Confluence Wiki, but I am trying to customize a layout with a horizontal top navigation for pages and vertical left navigation for children of the page the user is on. I have been successful in editing a decorator (main) page to do this, but it is in a static fashion (which defeats the purpose of Wiki). Is there a way that I can customize the layout/decorator, yet keep the dynamic aspect of as pages are added they reflect in the navigation? Also I need to display a left column section if there are child pages.


    Any help or links to resources are greatly appreciated.

  8. Anonymous


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

    Can any one help in this regard.

    Thank you,


  9. Anonymous

    Decorators links is broken.

    1. Thanks for letting us know, I have updated the link. 

        1. Thanks for that. Have updated the link (again (smile)).

  10. How to add macros in the layouts.Can we do that.

  11. Hi,

    I want to restrict features for anonymous access.

    I want to hide the left sidebar and tools in order to limit only the read access (no export, no history, etc..) for anonymous users.

    I suppose that it's possible by customizing layout but I don't know how.

    Someone can help me? please

    Thank you in advance




    1. Hi Cedric, 

      You can use space permissions to prevent users from being able to edit or export, but this will not hide the tools menu, watch and share. 

      Some custom CSS in the space may enable you to hide some of these elements (including the sidebar).  I would recommend searching Answers as other users may have found workarounds to do this. 

  12. Has anyone upgraded since customizing the space layout? Given the warning that is provided, " The more dramatic the customisations are, the harder it will be to reapply your changes when upgrading."

    I am just wondering if there were any problems or gotchas that one should be aware of.


    1. William,

      We customized just about all of the space layouts ( When we upgraded, it was pretty painless. Of course, I had been pretty diligent with commenting the decorators, so it was easy to integrate my changes with the new ones.

    2. Hi William, the Upgrading Confluence page has some steps that you should follow when upgrading an instance that has customisations.   As Matthew notes, commenting your changes in the decorators helps a lot, as does making a list of files that you have customised. 

      1. Other things (besides layout decorators) to watch out for:

        • *.vmd files that you might have customized
        • Custom CSS files 
        • User-installed plugins (some get disabled or removed when upgrading)
        • Context root (if you customized it, it might get reset)
        • User macros (these are maintained, but ones with external references might break)
        • favicon/logo
        • Mail notifications might be different on the new version
        • URL rewriting might change (check your web.xml and urlrewrite.xml files)
        • New features added – you might have to manually disable new features (like the "Like" button)
        • Port/proxy/etc settings might need to be re-done
        • Custom PDF stylesheets
        • Custom HTML 
        • Color scheme settings (if you don't use entirely custom CSS)
        • Labels and label mappings



  13. Hi there, 

    I modified the layout file for one of my spaces in an attempt to hide the sidebar. I apparently damaged the .vmd file as now whenever I click on "space tools" I recieve an error and the page fails to load. 


    Is there anyway to manually locate the .vmd file to modify it back with the original settings? As I do have a copy of the original contents. 


    error I receive is quite long but could attach if needed. 

    1. Hi Paul, one thing to try would be to navigate directly to the Layouts page using this URL


      where <your-confluence> is your Confluence base URL and SPACEKEY is the spacekey of the space you edited. 

      If that doesn't work, you can find the decorator (.vmd) files in your Confluence install directory here  <CONFLUENCE-INSTALLATION>\confluence\decorators

      If you still have difficulties, feel free to contact Support for help. 

  14. Hello,

    I've got a stupid question, maybe you have already answered it before but with my poor English I can't find it.

    I want to customize a space main page so that a navigation tree appears when I enter the space, with URL like As for now, I don't see any navigation tree on left and there's only "Create" button on the main page despite I have already created couple pages. They're not visible on left anyway.

    How do I do that?


    1. Hi Dmitry,

      If you want to display a list of pages within the page content, you can use the Children Display Macro or the Page Tree Macro.

      As to why you're not seeing the page tree in the sidebar, if the space is using the default theme, and if you've created pages within the space, you should see the page tree. Maybe take a look at Configure the Sidebar, and if you don't have any joy there, try contacting support.