Documentation for Confluence 5.4.
Documentation for Confluence OnDemand and earlier versions of Confluence is available too.

Skip to end of metadata
Go to start of metadata

Icon

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.

Notes:

  • You need system administrator permissions to edit the CSS for a space or for the site.
  • This function is turned off by default. To turn it on, go to Confluence Admin > Security Configuration and choose 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 OnDemand.

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 on 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 at the top of the screen.
    Note: The 'Space Admin' option appears only if you are a space administrator for the space or you are a super user (a member 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  at top right of the screen, then choose Confluence Admin.
  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 

25 Comments

  1. I have created a CSS class that highlights text and designates it as an instructor note. Now how do I apply that to the text? In HTML I would use a <div class="inst_note"> or <span class="inst_note"> tag. I can't find documentation here that explains how to do the equivalent of using a <div> or <span> tag to apply a CSS class.

    1. Hi Will,

      You may want to try my way to get your stylesheet applied:

      1. Create the stylesheet on <space> -> Space Admin -> Stylesheet. Put the following:
        div.kampredo {color: blue}
        
      2. Create a page contains the following. Please note that in order to use html macro, you need to enable it in plugin manager.
        {html}
        <DIV class="kampredo"> this is kampredo </DIV>
        {html}
        

      Cheers,

      1. Anonymous

        Hi Arie Murdianto

        its is suitable for confluence 3.5.13 ?

        Thank you

         

  2. I've tried overriding paragraph margin in the space admin style sheet. I can make it bigger than default, but not smaller. How can I make it smaller, such as 1em instead of what appears to be 2em on either the top or bottom margin.

    Alternatively, is there a way to make a custom paragraph style available from the pull-down, so that a paragraph would have a 1X line spacing between paragraphs like the 'preformatted' style, but with the same font, etc. as the current paragraph style?

    Thanks

    1. I'm not sure exactly what the cause of your problem is without some sample styles, but it sounds like it's a problem with collapsing margins, where a larger margin on one element causes a large gap even though the other element has a smaller margin. Vertical margins in CSS "collapse", which means that the vertical margins of adjacent elements overlap with each other in most circumstances.

      If you want to reduce the paragraph spacing on a section of text in a page, I'd recommend writing a user macro that wraps the content in a div with an additional class – <div class="single-spaced">...</div>. You can then apply custom styles to reduce the margin on paragraphs and headings within those macros: .single-spaced p { margin: 0; }. You'll need similar styles for the headings.

  3. I'm using Confluence 3.5. I cannot overwrite the default style of h1, h2, h3, ..., h7 via Space Admin >> Stylesheet.

    Any customized class (for instance #header1) works.

    1. You need to understand how CSS specificity works to make styles that override Confluence's ones.

      In our stylesheet, we use ".wiki-content h1" as our selector. So your selector needs to be at least as specific in order to work correctly.

      1. Anonymous

        Adding ".wiki-content" in front of the default class does work!! Thanks a lot!

  4. My users want to add comments to pages and have the comment text to be single line spaced, but then they press enter it's always <p> and double spaced

    how can I change the default settings to be <br> instead of <p>

    I just want to make their comments single line spaced.

    The double line spacing is adding too much padding to the pages

    PS they also want to do it with out having to press sift-return for new single spaced new lines

    1. There isn't really an easy way, unfortunately. We looked at making this the default for Confluence, but it introduced a lot of problems in the editing experience – way more problems than there are now.

      You could create a user macro and some custom CSS, as I described to Jay above, but that's probably not as easy as just encouraging your users to use shift-return if they want to insert a line break rather than a paragraph break.

  5. We applied a lot of styles to a page, but now when we edit the page, the edit area of the page is about one inch tall. Can styles applied to a page affect the way the page appears when you edit it? Is there a way to turn off styles when you edit a page? I can post an image if that helps.

    Thanks

     

  6. The double-spacing of lines is giving my users problems as well.  There is too much wasted space in a document.  Is it possible to get back to the old "wiki markup" editing UI, instead of the WYSIWYG editor so that lines can easily be single-spaced? 

    Thank you.

  7. Hello all,

    I was having a hard time getting the custom css within the Space Admin to overwrite the global CSS (a problem I found a lot of other people had, but no solutions to). I found a very simple fix to this and thought I might share, hopefully save someone else the headache!

    Normally, to define a custom style for a particular space, you would go to Space Admin > Stylesheet and then enter your CSS, cross your fingers, hold your breath, and hope that it actually works. Well, if it doesn't, take that fancy custom CSS, and go to Space Admin > Edit Space Layout. In the Header section, paste in your CSS and add {style} open and close tags.

    {style}

    .myCoolThing {display: block;}

    {style}

    Works like a charm! Good luck!

     

    1. side note: This trick is best used when you are trying to avoid using !important. The first step, before going into the Edit Space Layout sections, would be to add !important to your CSS within the Stylesheet. This should overwrite the global CSS with no problems. Because of custom jQuery I was using, the !important tag was not an option. In the Space Stylesheet, your CSS would look like this:

      .myCoolThing { display: block !important; }

      Hope this helps!

  8. Anonymous

    I like the things that can be created with CSS3, for example nice buttons without using image file; so, the page loads faster is a few buttons:
     http://www.coursesweb.net/css/buttons-css_cs
    Only with css /css3.

  9. Hi All,

     

    I am working on a GUI styling guide, please fell free to visit http://www.mos-eisley.dk/display/it/Styling+Confluence

    1. Thanks for the link, Normann. Please note that we are planning some significant changes to the web interface for Confluence 5.0, due to be released in a couple of months. More details here:

      I notice you're already referring to Confluence "4.x" in your page titles. This is a good approach – clear indicating which version your documentation refers to, so there is no confusion.

  10. The text says I need system admin permissions "to edit the CSS for a space or for the site".  We have a large confluence installation and I am not one of the admins, but I have created several spaces and would like to be able to use css to fix some deficiencies in Confluence rendering.  Do I really need to ask the admins for system admin permissions to be able to add css to my own spaces?  If so, why is it designed this way?  Why can't anyone add css to their own spaces?  At least, that relaxed permissions mode should be an option.

  11. Anonymous

    I'm trying to control table cell padding in confluence 5.  Anybody know how to use CSS to control this?

  12. Please correct link "CSS Resources section" in page. This link go on same page, not "Resources section".

    1. Oops! Good pickup (smile) I've fixed that up now, thanks for letting us know.

  13. Anonymous

    I've created a css for the site and change a lot of properties & values (so have i a large css). So far so good, it works great, but ...

    How can i change for some spaces only few (3-4) of the values without paste the whole css into space-stylesheet? I mean a reason like this:

    <head> ...
    <link type="text/css" rel="stylesheet" ... my_for_site.css>
    ...
    <style> ... -color: red; ...</style>
    </head>

    but not - like in html - for single dokuments. I'm looking for a reason for single spaces!

  14. Anonymous

    I'm again. No answer is an answer too. i understand it as 'search by yourself' (smile)
    CONF-27929 - Allow Space Stylesheet to work alongside Global Stylesheets New

  15. I created a css for my space. While the background color is getting applied and so is the font-size, the font color is not getting applied in my pages. Can anyone respond to this asap?

    1. Hi Vamsi, You might want to ask your question over at Atlassian Answers - you will get a faster response than here in the docs.