Tutorial: Drupal Bootstrap Subtheme with LESS

Bootstrap is our favorite starter theme for Drupal 7. However, the documentation is a little out of date and incomplete for Bootstrap 3.1.x and newer. The template files are also in an unusual place, making getting started with the subtheme trickier than it needs to be.

To save you some frustration and as a reference for our staff, I’ve prepared a step by step guide for creating your own subtheme. Our preferred method is to compile Bootstrap from source we can take advantage of the LESS files.

Overview

1. Get Bootstrap Theme
2. Create the subtheme directory and copy files
3. Configure your .info file
4. Download Bootstrap source
5. Compile the LESS files
6. Enable Your Subtheme
7. Copy template files from the parent theme (Optional)
8. Closing

1. Get Bootstrap Theme

1. Download the Drupal Bootstrap theme
   1. Extract/upload to your sites/all/themes
   2. There is no need to activate the theme. We only need this to set up the subtheme
2. Download/Enable jQuery Update
   1. Extract/upload to your sites/all/modules
   2. Set the “Default jQuery Version” to 1.9
   3. Set “Alternate jQuery version” to 1.5 (This prevents issues with AJAX heavy modules like Views)

 

2. Create the subtheme directory and copy files

1. Create a new folder for your subtheme inside of sites/all/themes.
   1. In our example, we’ll call our subtheme my_subtheme, so we should have an empty directory at sites/all/themes/my_subtheme.
2. Copy all the files from sites/all/themes/bootstrap/bootstrap_subtheme to sites/all/themes/my_subtheme
3. Your subtheme directory should look like this:
   

3. Configure your .info file

1. Rename bootstrap_subtheme.info.starterkit to my_subtheme.info. Remember to replace “my_subtheme” with the name of your own subtheme.
2. Edit my_subtheme.info with your text/code editor of choice and give it a unique name and description:

   name = My Awesome Bootstrap subtheme
   description = A Bootstrap Sub-theme customized for this particular project
   core = 7.x
   base theme = bootstrap

3. Uncomment scripts files. Since we’re going to compile from source and NOT use the default Bootstrap CDN,uncomment all the  “Scripts” section by removing the semi-colons ; in front ofeachofthejavascript files:

   scripts[] = 'bootstrap/js/affix.js'
   scripts[] = 'bootstrap/js/alert.js'
   scripts[] = 'bootstrap/js/button.js'
   scripts[] = 'bootstrap/js/carousel.js'
   scripts[] = 'bootstrap/js/collapse.js'
   scripts[] = 'bootstrap/js/dropdown.js'
   scripts[] = 'bootstrap/js/modal.js'
   scripts[] = 'bootstrap/js/tooltip.js'
   scripts[] = 'bootstrap/js/popover.js'
   scripts[] = 'bootstrap/js/scrollspy.js'
   scripts[] = 'bootstrap/js/tab.js'
   scripts[] = 'bootstrap/js/transition.js'

4. Disable Bootstrap CDN. Remove the semi-colon in front of:

   settings[bootstrap_cdn] = ''

4. Download Bootstrap source

Download Bootstrap source and upload it to your subtheme folder. The folder names may start getting confusing here because the word “bootstrap” is part of the theme name as well as the source code. Be sure to put the files inside of your subtheme folder. It should look like this when you’re done:

my_subtheme/bootstrap/
├── less/
├── js/
├── fonts/
├── dist/
│   ├── css/
│   ├── js/
│   └── fonts/
└── docs/
    └── examples/

The only folders you need from source are less, js, and fonts. The rest is optional, but it doesn’t hurt to have them in there.

Errors with variables.less

The subtheme starterkit has its own set of less files in the less folder. The 7.x-3.0 release of Drupal Bootstrap contains an old variables.less file that only works for versions 3.0.x of Bootstrap. If you try to compile it, you may get errors about undefined variables.

To get around these errors, replace the variables.less file at .../my_subtheme/less/variables.less with the one from the Bootstrap source at .../my_subtheme/bootstrap/less/variables.less. Bootstrap 3.1.x contains new variables and deprecated some variables, so you’ll want to use the latest variables.less file to compile with.

5. Compile the LESS files

Compile the LESS files to create your style.css, which contains all of the Bootstrap CSS , Drupal-specific overrides (overrides.less), and your own custom code.

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

6. Enable Your Subtheme

Enable your subtheme from Drupal. If everything went well, you should see the default Bootstrap styles loaded. The BootstrapCDN should not be loading any files, but you can check your theme settings to make sure. “BootstrapCDN version” should say disabled:

7. Copy template files from the parent theme (Optional)

If you plan on making only CSS changes to your theme, you can skip this step.

However, for more customized themes, you’ll want to modify the page.tpl.php and html.tpl.php files.

Copy page.tpl.php and html.tpl.php from sites/all/themes/bootstrap/theme/system to your subtheme’s templates folder at sites/all/themes/my_subtheme/templates

Flush the theme cache so Drupal will recognize the new files.

8. Closing

As you can see, setting up a Drupal Bootstrap subtheme can be a pain in the ass. If you develop websites for a living and work on many projects, you should look into creating your own git repository with all the necessary files and configurations. We maintain a repository for a generic “Bootstrap Subtheme” that can be enabled and used as is, saving about 20-30 minutes per new set up.