HowTo create a custom Redmine theme¶

Redmine offers basic support for themes. Themes can override stylesheets (application.css) and add some custom javascript.

Creating a new theme¶

Create a directory in public/themes. The directory name will be used as the theme name.

Example:

public/themes/my_theme

Create your custom application.css and save it in a subdirectory named stylesheets:

public/themes/my_theme/stylesheets/application.css

Here is an example of a custom stylesheet that only override a few settings:

/* load the default Redmine stylesheet */
@import url(../../../stylesheets/application.css);

/* add a logo in the header */
#header {
    background: #507AAA url(../images/logo.png) no-repeat 2px;
    padding-left: 86px;
}

/* move the project menu to the right */
#main-menu { 
    left: auto;
    right: 0px;
}

This example assume you have an image located at my_theme/images/logo.png.

You can download this sample theme as a starting point for your own theme. Extract it in the public/themes directory.

NOTE: If you have enabled caching per BrowserCaching, make sure you append a ?version to the include and update it whenever you update redmine to avoid your user's browsers grabbing the old application.css file whenever you upgrade redmine. @import url(../../../stylesheets/application.css?4.3.2);

Adding custom javascript¶

Simply put your javascript in javascripts/theme.js and it will automatically be loaded on each page (Redmine >= 1.1.0 only).

Setting a Favicon¶

Put your favicon in favicon directory and it will automatically be loaded instead of default one on each page. The name of the favicon file can be anything.

Applying the theme¶

Go to "Administration -> Settings" and select your newly created theme in the "Theme" drop-down list. Save your settings.
Redmine should now be displayed using your custom theme.

If you are using Redmine < 1.1.0, you may need to restart the application so that it shows up in the list of available themes.

Directory structure of themes¶

A theme consists of the following files:

• favicon/<favicon file> (optional): favicon for the theme
• javascripts/theme.js (optional): custom JavaScript for the theme
• stylesheets/application.css (required): CSS for the theme

public/
  +- themes/
       +- <theme name>/
            |
            +- favicon/
            |    +- <favicon file> (e.g. favicon.ico, favicon.png)
            |
            +- javascripts/
            |    +- theme.js
            |
            +- stylesheets/
                 +- application.css