The information in this page relates to customisations or development changes in Confluence. Consequently, Atlassian Support cannot guarantee to provide any support for the steps described on this page. Please be aware that this material is provided for your information only and that you use it at your own risk.

This page explains the facility for changing the look and feel of Confluence with CSS.

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. You can upload a CSS text file, or simply type in a stylesheet, and apply it to a space or even a whole Confluence site.

Note: By default, only system administrators can edit the CSS for a space or for the site. To allow any user with Space Admin permissions to edit the CSS for a space, go to  > General Configuration > Security Configuration and select 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.

On this page:

Related pages:

(warning) The information on this page does not apply to Confluence Cloud.

Considerations for Using Custom CSS

CSS Knowledge is Required

If you are not familiar with CSS, see the links in the CSS Resources section below. 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.

Custom CSS does not apply to Admin screens

Any CSS styling applied to your site will not be applied to the Administration console. This is to ensure changes to CSS do not prevent administrators from accessing Admin functions in future.  

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.

Note about 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. Check the Supported Platforms page to find the list of supported web browsers and browser versions on this page.

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:
  1. Go to the space and choose Space tools > Look and Feel from the bottom of the sidebar
  2. Choose Stylesheet then Edit.
  3. Paste your custom CSS into the text field.
  4. Save your changes. The new CSS will be visible on all content pages in the space.

If your space uses the Documentation theme:

  1. Choose Browse > Space Admin from the header

    Note: The Space Admin option appears only if you have space admin permissions, or if you're part of the 'confluence-administrators' group.

  2. Click Stylesheet in the left-hand panel under the heading 'Look and Feel'.
  3. Choose  Edit.
  4. Paste your custom CSS into the text field.
  5. Save your changes. The new CSS will be visible on all content pages in the space.

To edit your global CSS stylesheet:
  1. Choose the cog icon , then choose General Configuration under Confluence Administration
  2. Choose Stylesheet.
  3. Choose Edit.
  4. Paste your custom CSS into the text field.

  5. Choose Save. 

Note: 

  • The new CSS will be visible across all spaces, provided they do not define their own custom stylesheet and are not using a theme. This CSS will also overwrite all styles defined in custom global themes.
  • You may be able to add CSS to your site by choosing Custom HTML in the administration section, and adding your CSS definitions to the HEAD or BODY of the page. You should only use this option if you cannot achieve the desired results via the global stylesheet.

Follow the Tutorial

Follow the examples in the Basic Styling Tutorial to get started.

CSS Resources 

  • No labels