Creating a LESS-based Bootstrap subtheme

I've been a long-time Omega themer (and I especially love Omega 4), but outside of Drupal I always use Bootstrap as a starting point for styling a site. The Bootstrap theme has come a long way since I last evaluated it, so I gave it another try recently. It was tricky to set up a subtheme, so I'm sharing my steps here.

I found some clues from this article, but refined the process a bit.

Download the Bootstrap base theme

There hasn't been a stable release of the Bootstrap theme recently (as of the time of this writing), so I grabbed the latest DEV which contains lots of bug fixes and extends Bootstrap theming support into more nooks and crannies of Drupal's interface. If you have drush:

drush dl bootstrap-7.x-3.x-dev

Create your sub-theme

You could do this the hard way, by copying the "starterkits/less" folder out of the bootstrap theme folder into your own space (e.g., "sites/default/themes", renaming "less" to something like "bootstrap_subtheme"). Or, just use drush:

drush cc drush
drush bootstrap-wizard

(Choose to make it a sub-theme of Bootstrap, using the LESS starterkit.)

Install Bootstrap library source code

Since we're compiling the CSS from LESS, we won't need the Bootstrap distribution, but we will need the source code. Also, the Bootstrap JS files are included via our sub-theme's .info file. So grab the latest Bootstrap 3 release (3.3.4 at the time of this writing) and install it into your sub-theme (in our example above, "bootstrap_subtheme/bootstrap"). The only folders you need are "fonts", "js", and "less".

Tweak the sub-theme LESS

Inside the "less" folder of your sub-theme, there are several .less files. The main one is style.less, which is what you'll compile later. It brings in bootstrap.less (which is a copy of the same file in your bootstrap library folder), and then adds Drupal overrides, and then some blank header, content, and footer files.

At the time of this writing, the contents of bootstrap.less were different than what shipped with the Bootstrap library. I recommend pasting in the contents of bootstrap/less/bootstrap.less, except the first line, so that your less/bootstrap.less file looks like this:

// Local variable overrides.
@import "variables";

// Core mixins
@import "../bootstrap/less/mixins";

// Reset and dependencies
@import "../bootstrap/less/normalize";
@import "../bootstrap/less/print";
@import "../bootstrap/less/glyphicons";

// Etc...

Moving on to variables.less, the one that shipped with the starterkit (at the time of this writing) had deprecated Bootstrap variables, so I rewrote mine to basically load in the variables from the Bootrap library and then override the ones I care about. That way I can easily upgrade the Bootstrap library at a later date with minimal need to update my sub-theme's LESS. My variables.less looks like this:

// Import Bootstrap's variables, then override them below.
@import "../bootstrap/less/variables";

// Update path to fonts.
@icon-font-path: "../bootstrap/fonts/";

Note that I changed the icon path. This fixed the references being broken when my LESS compiled to CSS.

Compile your LESS to CSS

Compiling your LESS is pretty easy. You need to install LESS first, but it should be as simple as:

npm install -g less

Then from your theme's folder, execute the following to compile your LESS into your sub-theme's style.css:

lessc less/style.less > css/style.css

That's it! You now have a LESS-powered sub-theme. Add your custom theming to the built-in header.less, content.less or footer.less files. I usually prefer to create a separate file for each type of thing—content type, navigation, homepage, etc). Just remember to remember to reference any additional files in style.less.

Last thoughts

Unless you already have it a newer version of jQuery on your site somehow, you'll probably want to install jQuery Update and configure it to use at least jQuery 1.9, the minimum requirement for Bootstrap.

Oh, and don't forget to enable your new sub-theme!