This page last changed on Jun 02, 2009 by rhartono.

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 easily upload a CSS text file and apply it to a space or even a whole Confluence instance. See this page for instructions.

This function is not on by default. To allow space admins to edit stylesheets, go to the general configuration section of the admin console and turn on "Enable Custom Stylesheets for Spaces".

Creating CSS styles that works 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 carefully 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 which alters a Confluence menu.

Considerations for Using Custom CSS

CSS Knowledge is Required

If you're not familiar with CSS, this page has an accessible introduction. You should spend some time to become confident with Cascading Style Sheets before you start editing your Confluence instance.

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.

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.

Follow the Tutorial

When you're ready, follow the examples in the Basic Styling Tutorial or the more advanced Styling Tabs in Confluence to get started.


RELATED LINKS

Basic Styling Tutorial
Styling Tabs in Confluence
Styling Fonts in Confluence
Including Cascading Stylesheets in Themes

Document generated by Confluence on Dec 10, 2009 18:40