Styling Confluence with CSS
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.
> 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 customizing 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.
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 the various web browsers supported by Confluence.
CSS Customization is Not Supported
As creating custom CSS has potentially limitless possibilities, Atlassian will not support issues that are caused by or related to CSS customization.
Getting Started
Editing the CSS
- Go to the space and choose Space tools > Look and Feel from the bottom of the sidebar
- Choose Stylesheet then Edit.
- Paste your custom CSS into the text field.
- Save your changes. The new CSS will be visible on all content pages in the space.
- Choose Administration > General Configuration > Stylesheet.
- Choose Edit.
- Paste your custom CSS into the text field.
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.