HowTo create a custom Redmine theme » History » Revision 13
Revision 12 (Jonathan Cormier, 2021-11-05 22:08) → Revision 13/14 (Takashi Kato, 2025-09-28 09:50)
h1. HowTo create a custom Redmine theme Redmine offers basic support for themes. Themes can override stylesheets (application.css) and add some custom javascript. NOTE: From Redmine 6.0, the location for themes changed from @public/themes@ to @themes@. If you are creating a theme for a version prior to 6.0, please read @themes as @public/themes in the following instructions. h2. Creating a new theme Create a directory in @/themes@. @public/themes@. The directory name will be used as the theme name. Example: themes/my_theme public/themes/my_theme Create your custom @application.css@ and save it in a subdirectory named @stylesheets@: themes/my_theme/stylesheets/application.css public/themes/my_theme/stylesheets/application.css Here is an example of a custom stylesheet that only override a few settings: <pre><code class="css"> /* 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; } </code></pre> 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 @/themes@ @public/themes@ directory. *NOTE*: From Redmine 6.0, The code @@import url(../../../stylesheets/application.css)@ shown in If you have enabled caching per [[BrowserCaching]], make sure you append a ?version to the example above is automatically converted include and update it whenever you update redmine to @@import url(“/assets/application-29b28b2c.css”);@ when Redmine starts. The combination of numbers and letters at avoid your user's browsers grabbing the end of the filename is a hash value calculated from the file's contents. Since the filename changes old application.css file whenever the content is modified, issues like display corruption caused by browsers using outdated cached versions are avoided. you upgrade redmine. @@import url(../../../stylesheets/application.css?4.3.2);@ h2. Adding custom JavaScript javascript Simply put your JavaScript javascript in @javascripts/theme.js@ and it will automatically be loaded on each page. page (Redmine >= 1.1.0 only). *NOTE*: From Redmine 6.0, When specifying image paths in JavaScript, use the @RAILS_ASSET_URL@ pseudo-method as shown in the example below. For more detailed conversion specifications, refer to "README of propshaft":https://github.com/rails/propshaft?tab=readme-ov-file#referencing-digested-assets-in-css-and-javascript Source: <pre class="javascript"> export default class extends Controller { init() { this.img = RAILS_ASSET_URL("/icons/trash.svg") } } </pre> Transformed: <pre class="javascript"> export default class extends Controller { init() { this.img = "/assets/icons/trash-54g9cbef.svg" } } </pre> h2. 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. h2. 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. h2. 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 <pre> themes/ public/ +- themes/ +- <theme name>/ | +- favicon/ | +- <favicon file> (e.g. favicon.ico, favicon.png) | +- javascripts/ | +- theme.js | +- stylesheets/ +- application.css </pre>