This documentation has moved. For the most recent documentation, check out Please update your bookmarks and links.

Skip to end of metadata
Go to start of metadata

Customise the Left Hand Sidebar

In ThemeBuilder the sidebar is added as one macro that pulls in the default Confluence content for this area. If you want to change the sidebar then you need to rebuild the content in a new custom panel.

Replace the default content macro with a custom content panel

In ThemeBuilder panel editor

  1. Select the skin you want to edit
  2. Click the ‘New Panel’ button
  3. Change the name and description to help you identify the panel

  4. Then edit the ‘with-sidebar’ panel to replace the macro that inserts the Confluence sidebar with your new ‘custom-sidebar’
    Select and remove the code

    <ac:macro ac:name="panel-element">
    	<ac:parameter ac:name="element">page.ia-sidebar</ac:parameter>

  5. Use the ‘Insert Macro’ button to browse for the ‘Builder Panel’ macro

  6. Add the name of your new sidebar to the ‘Panel’ field

  7. Click ‘Insert’ and check that the new macro is in the correct position, replacing the ‘panel-element’ macro.
    See Scrolling Sidebar for additional code you may want to add here.

  8. Click ‘Apply’ to save those changes and then open a new browser tab or window to view a page that has this skin applied.

The left hand sidebar is now blank and ready for you to add your custom content.

Add custom content to your panel

See ThemeBuilder Debugging Tools for help with this section.

Now you have a blank space to work with you can add custom content to the sidebar. By adding ‘?skin=root’ to the page url we can flick back to the default ThemeBuilder skin to see the existing content and decide what we want to add or exclude. You could also refer to a print or screenshot of the default page.

Scrolling Sidebar

To have a scrolling sidebar you must wrap your content in this HTML div code so it will use the Confluence default functionality.

<div class="acs-side-bar ia-scrollable-section">
...your content here



This example will show you how to add a Pagetree menu and the links to Space Tools, Pages and Blogposts.

Pagetree Menu

The Pagetree macro displays a simple vertical navigation that has many configurable parameters including:

  • A ‘this space only’ search box.
  • Content from different spaces or the current one.
  • One click ‘expand all’ or ‘hide all’ links.

Used here with the parameters ‘root=@home’ and ‘searchbox=true’ it provides a useful left hand navigation for a custom sidebar.

  1. Go to the 'custom-sidebar' panel
  2. Use the 'Insert Macro' button to find and add the 'Pagetree' macro.
  3. Add '@home' in the 'Root Page' field, the scroll down and check 'Include Search Box above Page Tree'
  4. Click insert and you should see this code in your panel.

<ac:macro ac:name="pagetree">
 <ac:parameter ac:name="root">@home</ac:parameter>
  <ac:parameter ac:name="searchBox">true</ac:parameter>


Finally add some CSS to space the Pagetree menu. See Custom CSS page if you need help with this.

.plugin_pagetree {
    margin: 10px;

Page and Blogs Navigation

You can use the ‘web-section’ macro to place the sidebar navigation.

This example uses a styled <hr /> for spacing between the custom sidebar elements.

.ia-fixed-sidebar hr {
    margin-left: 14px;
    width: 90%;


  1. In the ‘custom-sidebar’ panel place the cursor where you want to add the Pages and Blog posts links. Use the ‘Insert Macro’ button to add a ‘web section’ macro. See Menu - Web Item and Menu - Web Section for how to find and use the menu location values.
  2. To recreate the sidebar Pages and Blog links use ‘‘ in the ‘location’ field, and uncheck the ‘Show Icons’ box.

  3. The code will be

    <ac:macro ac:name="web-section">
      <ac:parameter ac:name="location"></ac:parameter>
      <ac:parameter ac:name="icons">false</ac:parameter>

  4. Save the macro and then browse to a page with the custom sidebar. The Page and Blog links now show under the Pagetree menu


Space Tools

For the ‘Space Tools’ link you may want to only show this to certain users or groups, so this example will use the ‘builder-show’ macro to only display that link to ‘confluence-administrators’. You can use any group in Confluence with builder show or hide, as well as user, decorator, mode and many others. The ThemeBuilder debug comments will show many of these values in the source of a page.

The process here is similar to the one used to add the Pages and Blogs links, but we are going to wrap the menu macro in another macro that will only show the contents within on the specified condition.

  1. In the 'custom-sidebar' panel place the cursor where you want the 'Space Tools' link to show.
  2. Use 'Insert Macro' to find the 'builder-show' macro.
  3. Scroll down to the 'groups' field and add the name of the group you want to show this content to

  4. Click 'Insert' to place the macro in your panel.
  5. Now place the cursor between the   <ac:rich-text-body> tags and create a space for the next macro.

  6. Use 'Insert Macro' to find and add the 'web section' macro and use the values ‘‘ in the ‘location’ field, and uncheck the ‘Show Icons’ box.
  7. Insert the macro and it should look like this.
    (don't forget, if you have problems with the formatting of panel code you can use the 'Prettify' button to re-indent everything)

    <ac:macro ac:name="panel-show">
      <ac:parameter ac:name="group">confluence-administrators</ac:parameter>
        <ac:macro ac:name="web-section">
          <ac:parameter ac:name="location"></ac:parameter>
          <ac:parameter ac:name="icons">false</ac:parameter>
  8. Click 'Apply' on the panel editor, go to browse your page, and you will see the 'Space Tools' link has been added.

  9. Browse the page as a user not in the target group to confirm that the logic is working.



This is just a snapshot of the changes that can be made in this area. By combining menu macros and CSS styling you can completely change the way this area is used and valued within Confluence. If you have any suggestions or tutorials we can add please let us know.

  • No labels