Styling Confluence with CSS

This page explains the facility for making visual changes to the look and feel of Confluence with CSS.

On this page:

Introduction

Cascading Style Sheets (CSS) are an industry-standard way of styling a web page. The content of a page is rendered with HTML, and its look and feel is determined by CSS files.

With the release of Confluence 2.10, you can upload a CSS text file and apply it to a space or even a whole Confluence instance.

This function is turned off by default. To allow space administrators to edit stylesheets, go to the security configuration section of the Confluence Administration Console and turn on 'Enable Custom Stylesheets for Spaces'.

Creating CSS styles that work seamlessly across different browsers is a delicate task for basic web sites, and reasonably challenging when customising web applications like Confluence. It is important to test each change that you make and ensure it works as expected in all areas of Confluence – for example, on the Confluence Dashboard as well as on regular pages.

In order to get you started, we have compiled this introduction, a basic styling tutorial and a more advanced tutorial.

Considerations for Using Custom CSS

CSS Knowledge is Required

If you are not familiar with CSS, the w3schools page has an accessible introduction. You should spend some time to become confident with Cascading Style Sheets before you start editing your Confluence style sheets.

Security

Custom CSS can be used to inject scripts into a page, opening the risk of cross-site scripting (XSS) attacks. With this feature enabled, space administrators could upload styles that steal other users' login credentials, trick their browsers into performing actions on the wiki without their knowledge, or even obtain global administration privileges. As such, this feature is disabled by default. Confluence administrators should only enable custom CSS if they are comfortable with the risks listed in this paragraph.

Scaling

Each page needs to scale. Depending on the resolution of the user's screen, the content should render intelligently. Your designs needs to degrade gracefully. Try resizing each page that exists in Confluence. There are quite a few pages in the browse-space-section, like drafts, labels, page hierarchy, and so on. Your style has to work everywhere, not just in the first page you happen to be looking at.

Features Cannot Be Disabled

It is easy to turn off certain links, headers, or even menu items by simply setting their style to 'hidden'. This can help you to roll out Confluence to users that may not be very Wiki-savvy yet. The simpler the UI, the easier it may be for them to use. However, please remember that removing the link to a part of the application does not mean that the functionality is not available. Every user can still change their style from within their browsers, or access the URL directly. Don't rely on CSS to disable parts of Confluence.

Features Should Not Be Disabled

Users familiar with Confluence will expect to find the same controls that they are accustomed to. Removing buttons or controls from the interface is not advised as it may frustrate your users and cause them to circumvent your design by using direct URL access, as mentioned above.

Confluence Version Compatibility

Be aware of any plans to upgrade your Confluence instance. Future versions of Confluence may not be compatible with your custom CSS — this may cause your CSS to break, requiring maintenance when Confluence is upgraded. Ask your Confluence administrator for more information.

Test on Different Web Browsers

As a rule you should test your modifications on different web browsers. Internet Explorer, Firefox, Opera and Safari (on Mac OS X) are some of the more popular browsers.

Supported Web Browsers

Please ensure that you are using one of the web browsers supported by Confluence. If you are using an unsupported browser or browser version, some features may not work correctly. You can find the list of supported web browsers and browser versions on this page: Supported Platforms.

CSS Customisation is Not Supported

As creating custom CSS has potentially limitless possibilities, Atlassian will not support issues that are caused by or related to CSS customisation.

Getting Started

Editing the CSS

To edit a space's CSS style sheets:

Go to the 'Space Admin' tab of the Browse Space view. To do this:
- Go to a page in the space, open the 'Browse' menu and select 'Space Admin'.
  'Space Admin' is displayed only if you are a space administrator for that space or you are a Confluence system administrator.
Click 'Stylesheet' in the left-hand panel under the heading 'Look and Feel'.
Click 'Edit'.
Paste your custom CSS into the text field.
Click 'Save'. The new CSS will be visible on all content pages in the space.

Follow the Tutorial

Follow the examples in the Basic Styling Tutorial or the more advanced Styling Tabs in Confluence to get started.

Child pages