Customizing the Confluence Sidebar and Page Navigation with Scroll Versions

8 min read /

Have you ever wondered whether you can display additional content (such as Atlassian's Confluence support docs) in the navigation sidebar and on each page?

Well, I was wondering about this myself. And when I came upon the solution, I was quite surprised about where it was: in K15t Software’s support docs for the Scroll Versions theme. A prime example of RTFM (read the fantastic manuals)!

In the sidebar, the help site provides access to previous product versions and other download formats. On top of each page there's a version notice.

This week, I discovered just why it’s a good idea to read the manuals – at least when it comes to the Scroll Versions Documentation. I've been working with Scroll Versions for a long time now – managing and publishing concurrent versions of documentation in Confluence as an author and a consultant. And I always wondered how Atlassian could customize the navigation sidebar of their Confluence pages. But then I read the Scroll Versions support docs carefully. And I was surprised to discover that I can do this with Scroll Versions – it's one of the add-on's standard features!

I don't even need to have CSS coding skills to customize the navigation sidebar or provide a space-wide page header or footer. To add or modify its contents, the only thing you need to do is edit special Confluence pages that are hidden by default.

Customizing the Navigation Sidebar

I've learned from the Scroll Versions docs that it’s very easy to customize the navigation sidebar:

  1. Make sure that Scroll Versions and the Scroll Versions theme have been enabled in your Confluence space.
  2. In that space, create a page with the exact name:  _SvNavigation
  3. Edit this page to display all of its content in the navigation sidebar.

By the way, during step 2, you can hide this page from viewers by creating an include library with Scroll Versions and moving it there.

Building your sidebar

Because the content of the _SvNavigation page replaces the entire default navigation sidebar, you may want to add/restore certain default elements:

  • First, a search box: Insert the "Page Tree Search" macro from the macro browser. Or you could choose the "Livesearch" macro that displays matching results as you type.
  • The page tree navigation itself: Below you might want to insert a page tree – either using the Confluence default "Page Tree" macro, or with the "Sv page tree" macro offered by Scroll Versions. 
    The "Sv page tree" macro builds a tree with exactly the same look and functionality as the default page tree, whereas the default "Page Tree" never displays top-level pages.
  • And finally: Insert your custom content, such as additional links, notes or disclaimers of your choice.

Images for your sidebar navigation

You’re not content merely to put additional text in the navigation sidebar? As you can see in the example above, I wanted to place an image in the sidebar. To do this, it's crucial to use a graphic that’s attached to another page or on another website. Otherwise your sidebar image cannot be displayed properly on every page in the space. This is due to the way Confluence embeds attachments from the same page (Confluence uses relative links instead of absolute ones that would be available in any context).

Page Headers and Footers with Dynamic Content

If you have important information that’s relevant to the whole space, it can be useful to display a notice above each and every page in a Confluence space.

For example, Atlassian provides a box above the "normal" page content. It tells readers which Confluence version is referred to in the documentation space. The info box also references earlier versions of the product documentation and links to the Confluence OnDemand documentation.

In addition, Atlassian provides call-to-action buttons, and a copyright notice in the footer of each support page:

To use space-wide headers and footers this way, you could modify your Confluence theme. But if those content snippets are changed regularly, this can be pretty inconvenient. 

Instead, wouldn't it be cool if the header and footer content could be managed on a (hidden) Confluence page that has a change history or even versioning, like the rest of the space's pages?

Once again, I was surprised to find that Scroll Versions already supports this out of the box. And the method is the same as for creating a custom sidebar.

  1. Create a page called _SvContentHeader to create a custom header, or _SvContentFooter for a footer.

  2. As with the sidebar page, the best place to put this page is in a hidden include library in the same space.
  3. Edit your header or footer as you wish.
  4. Images can be embedded in the same way as described above. As a rule of thumb, don't use images attached to the same page!
  5. You're done.

Advanced Customization

Now you know that you have full freedom of Confluence editing when creating a custom navigation sidebar, header or footer. You can format text, use macros, embed images or use conditional content, another cool feature of Scroll Versions. But in some cases, you could need even more flexibility.

Styling your sidebar, header or footer with CSS

Are you a web designer or do you have some Cascading Style Sheets (CSS) skills? If so, you can have total control over style and layout of header, footer, or sidebar content, because Scroll Versions has a CSS class for each area:

  • The .sv-navigation class lets you style the navigation sidebar.
  • .sv-content-header applies to the Scroll Versions theme header.
  • And .sv-content-footer is the class name of the corresponding footer wrapping element.

Displaying elements only for some users or groups

Elements in the navigation sidebar or in a header or footer can also be switched on and off, depending on the user logged on to Confluence. This feature lets you provide notes for specific user groups only, or hide some of your custom links from others.

To control the visibility of elements and to hide content from certain user groups, I recommend using the ServiceRocket Visibility Plugin with its {show-if} or {hide-if} macro from ServiceRocket, available free of charge from the Atlassian Marketplace.

Full control over layout and style

Still not enough customization for you? In that case, I recommend using Scroll Viewport – the latest Confluence add-on from K15t Software – to turn your Confluence space into a completely personalized website. It transforms your favorite Wiki into a CMS – and keeps viewing and editing separate. And Scroll Viewport offers much more than merely a Confluence theme. It allows you to define templates with plain HTML, CSS and JavaScript, and viewports for pages and blog posts. The result is a whole new website with SEO-friendly URLs – and it’s lightning fast. Try Scroll Viewport with a 30-day trial!

What’s Next?

Want to Learn How to Do Agile Documentation?

Read more about it on Rock the Docs.