One of the first things people do to customize their Redmine or ChiliProject is to install a theme. Redmine has supported custom themes since version 0.6.0 (October 2007).

In my opinion a custom Redmine theme can really make your site stand out and also make Redmine much more usable than the default theme. But first, I want to explain what a custom Redmine theme actually is.

There are two types of themes for Redmine. The first is what I call “Basic themes” which I’ll be describing below. The second type are called “theme plugins” which I’ll be writing about later.

Basic themes

Basic themes are what is referred to in Redmine’s documentation most of the time. These are packages of CSS, JavaScript, and images that you can install and then enable in the administration panel. They are always system-wide and are meant to enhance or tweak the existing style of Redmine.

Basic themes are great if you want the same look in Redmine but perhaps with some new colors and styles. They are pretty limited though, especially if you want to re-organize how things appear on the page.

Minimum requirements for Redmine

To create a basic theme, you need to do a few things to have Redmine recognize the theme.

First you need to create a new directory in public/themes with the name of your theme, like public/themes/my_new_theme.

Second you need to add a CSS stylesheet to the theme called application.css. This file must go into the stylesheets directory and be named application.css. Example: public/themes/my_new_theme/stylesheets/application.css.

That is all you need to do but at this point you’ll won’t have much of a theme. In fact, you won’t have many styles at all.

Importing the main application.css

Redmine defines its default styles and the default theme in a file called public/stylesheets/application.css. This file has all of the layout and positioning information but it also includes visual styles like background and color schemes.

You will want to import this stylesheet into your theme, otherwise you’ll have to do all the layout and positioning in your theme. Use the CSS @import statement to do this. Basically this loads another CSS file into the current one (it’s similar to PHP’s include and Ruby’s require statements). Make sure to put the @import at the top of the file, before any of your custom styles.

/* File: public/themes/my_new_theme/stylesheets/application.css */
@import url(../../../stylesheets/application.css);

At this point, you can now start to customize and tweak the styles for your custom theme.

Note: As part of the redesign of ChiliProject for 3.0 I’ve been trying to change application.css to be more generic. That way it doesn’t contain as many style statements and is easier to override styles in a theme. As you might expect with a 2,500 line CSS file, this is an ongoing process.

Customizing styles

I’m not going to cover customizing the CSS that much here. At this point it’s basic CSS development, so any book or site on CSS can help you.

Summary

That’s pretty much the basics to creating a Redmine theme.

1. Create a directory in public/themes named after your theme
2. Create an public/themes/YOUR_THEME/stylesheets/application.css file
3. Add the @import statement to the application.css to pull in the main Redmine styles
4. Select the theme in the administration panel under settings

Another good way to learn how to create a theme is to look at some examples. The alternative theme is included with Redmine and shows some of the things you can do. My Open Source ChiliProject also has a custom theme that is built for the ChiliProject 3.0 layout. Feel free to see how it works, but ask for permission before you use any of it.

Now a question for you, are you using a different theme for Redmine? Is it an open source one or a custom one you’ve created? Feel free to post a link to it, I’m curious about how some themes look.