Theming

Theming Blacklight

Blacklight uses the Twitter Bootstrap framework for styling the out-of-the-box UI. While there is some Blacklight-specific customizations, most (if not all) the "styling" (colors, fonts, etc) are handled by Bootstrap.

Bootswatches

One approach to styling Bootstrap-based sites is using "bootswatches", which are simple bootstrap themes that override SASS variables, mixins and declarations.

First, add the bootswatch-rails gem to your Gemfile (and run bundle install):

gem 'bootswatch-rails'

This will give you the set of themes from http://bootswatch.com/, converted to SASS and exposed to the Rails asset pipeline.

Out of the box, your application's blacklight stylesheet (generated by default to app/assets/stylesheets/blacklight.css.scss) looks something like:

@import 'bootstrap';

@import 'blacklight/blacklight';

To add the one of the bootswatch themes ('cerulean' in this example):

@import "bootswatch/cerulean/variables";

@import "bootstrap";

@import "bootswatch/cerulean/bootswatch";

@import 'blacklight/blacklight'

The bootswatch-rails documentation provides similar directions, a list of available out-of-the-box themes, and more.

As of this writing, not all bootswatch-rails themes seem to be bootstrap 2.1.x compatible, or do weird things to the Blacklight navbar, etc. Your milage may vary.

Developing a Customized "Local" Theme

In most cases, you will want to develop your own theme within your Blacklight app, outside of the Bootswatch gem. To do this, you can do the following in your app/assets/stylesheets directory:

1. create your own _variables.scss and _bootswatch.scss files in stylesheets/ (easiest way to do this is to copy those files from the bootstrap-sass project or an existing theme and customize from there)
2. change application.css to application.css.scss
3. add the import statements given in the above "theming" example to application.css.scss
4. delete blacklight.css.scss

So, your application.css.scss should look like this:

@import "variables";

@import "bootstrap";

@import "bootswatch";

@import 'blacklight/blacklight'