As of the release of Bootstrap 8.x-3.0-rc2 on August 3rd, 2016 the Bootstrap theme comes with its own SASS starterkit packed in. I recommend using that instead of creating your own from the LESS starterkit, and we now have a guide about exactly how to put the Drupal 8 Bootstrap SASS Starterkit in place.
You are excited about Drupal 8! You love Bootstrap! You appreciate the power SASS offers! So naturally you want to use the Drupal 8 Bootstrap theme and base a subtheme on it using SASS. There are unfortunately only two starter kit options that come packed in to the base theme: one for CDN and one for LESS. But we can leverage those subthemes and build exactly the configuration you want! This is a ground-up guide on how to implement that.
If you’re not already aware, the Drupal 8 Bootstrap theme has a lovely documentation page which this article borrows from for it’s installation portions. It’s a powerful reference that can be used to bridge the gap between Drupal and Bootstrap docs. You can find it at http://drupal-bootstrap.org/api/bootstrap/8
Additionally, this post is pretty closely based on an article written by Roland Michael dela Peña that did something very similar in the Drupal 7 version. You can read that original piece here: Using SASS in Bootstrap Drupal theme
This guide makes more than a few assumptions, but the key assumptions are:
- You have installed a working copy of Drupal 8
- Ruby is also installed on your machine, so you can get and install Compass if you don’t already have it to compile your SASS.
It’s also recommended that you have:
- Drush, because drush is great and if you do development for Drupal you need drush to run awesome CLI stuff.
With all that in place, we can get started with the first step.
Installing Drupal 8 Bootstrap with SASS
Step 1: Aquire Drupal 8 Bootstrap theme
You can get Drupal 8 Bootstrap pretty simply by running
drush dl bootstrap in your Drupal root directory (known from here on as
drupalroot ) if drush is installed. If not, you can pull the theme from the Drupal.org project page, then unzip the directory into
Note: At the time of this writing, Drupal 8 Bootstrap is still at 3.0-beta3. I don’t expect much change as long as the Bootstrap core on the theme remains at 3, but Bootstrap 4 is in alpha and I don’t know the roadmap, so that may change soon.
Step 2: Make your custom Drupal 8 Bootstrap subtheme
Most of the instructions in this step can be found in the READMEs scattered throughout the Drupal 8 Bootstrap theme as well as the official documentation page, but I’ve tried to be a little more straightforward here so it runs a little faster.
Drupal 8 Bootstrap comes loaded with two “starterkit” themes for you to create a child or subtheme with. You can find them in
drupalroot/themes/bootstrap/starterkits . For this, you’ll want to copy the
less theme and paste it directly into the themes folder at
drupalroot/themes . Rename the folder to your theme name, so the path should look something like
drupalroot/themes/mytheme , where
mytheme is the machine name of your theme.
Now comes the fun part: renaming everything in the theme to match
mytheme . Here’s the hit list of things to rename and otherwise alter inside of the folder
drupalroot/themes/mytheme , changing THEMENAME to your theme’s name:
config/install/mytheme.settings.ymlKey to note in this file is the
cdn_provider: ''setting that disables the Drupal 8 Bootstrap theme’s automatic use of a CDN.
config/schema/mytheme.schema.ymlMake sure you update the three spots where THEMENAME and THEMETITLE appear in this file as well.
info. Edit this file to set your theme’s name and description. Finally be sure to update the two THEMENAME instances in the libraries section.
With those files altered, you should have a working Drupal 8 Bootstrap subtheme. Navigate on your Drupal site to
/admin/appearance, scroll down the page and click ‘Install and set as default’ on your new theme.
TADA! Your theme is ready and running!
Well, OK, kinda. There’s no styling, but that’s because we don’t have anything in place to compile the LESS code, and that is fine because we’re about to breath some life into the system with SASS!
Step 3: Bolt on Bootstrap SASS
Let’s put some SASS in this theme!
Step 3A: Get your theme organized
Start by removing the
drupalroot/themes/mytheme/less folder from the theme. You won’t be needing it any longer. In its place, you’ll want to add a few new directories to
assetsWill hold all your new editables
assets/imagesWill hold the files to be turned into sprites using Compass
assets/sassWill hold all of your custom SCSS files
bootstrapWill carry all of the Bootstrap SASS source
imgWill hold your compiled images/sprites
Step 3B: Drop your SASS in place
When you decompress the Bootstrap SASS archive, the only parts you want are in the
assets folder. Pick up everything in that folder and paste it into your new theme’s
bootstrap folder at
Step 3C: Customize Your SASS
bootstrap folder you just created, you’ll want to retrieve two files and copy them to your
Once those are in place, rename
assets/sass/style.scss. This is now your core SASS file, and all of the includes need to be updated. Use find and replace in your editor to change “bootstrap/” to “../../bootstrap/stylesheets/bootstrap/” for all instances.
Finally, you want to find the line in
style.scss that imports variables and change it to use the copy in the
assets folder. It should be one of the first import lines in the file. Change it so that
@import "../../bootstrap/stylesheets/bootstrap/variables"; becomes
With this all of your SASS files are in place and ready to be compiled.
Step 3D: Configure Compass to work that SASS
Since you (hopefully) already have Ruby installed, you should be able to navigate to your
mytheme directory and install Compass for use:
gem update --system
gem install compass
This will automatically install SASS for you as well, if it’s not already there.
Normally you’d have compass do the dirty work of getting a project started for you, but since the configuration is a little peculiar we’ll build our own configuration. Create a file in
config.rb . Add this information to it:
<span class="n">http_path</span> <span class="o">=</span> <span class="s2">"/themes/mytheme"</span>
<span class="n">css_dir</span> <span class="o">=</span> <span class="s2">"css"</span>
<span class="n">sass_dir</span> <span class="o">=</span> <span class="s2">"assets/sass"</span>
<span class="n">images_dir</span> <span class="o">=</span> <span class="s2">"assets/images"</span>
<span class="n">fonts_dir</span> <span class="o">=</span> <span class="s2">"bootstrap/fonts/bootstrap"</span>
<span class="n">generated_images_dir</span> <span class="o">=</span> <span class="s2">"img"</span>
<span class="n">http_images_path</span> <span class="o">=</span> <span class="n">http_path</span> <span class="o">+</span> <span class="s2">"/"</span> <span class="o">+</span> <span class="n">generated_images_dir</span>
<span class="n">http_generated_images_path</span> <span class="o">=</span> <span class="n">http_images_path</span>
<span class="n">output_style</span> <span class="o">=</span> <span class="p">(</span><span class="n">environment</span> <span class="o">==</span> <span class="ss">:production</span><span class="p">)</span> <span class="p">?</span> <span class="ss">:compressed</span> <span class="p">:</span> <span class="ss">:expanded</span>
Take care that
http_path is changed to match your theme name.
Your SASS-powered Theme is Live!
With that in place you should be able to run
compass compile and
compass watch in your theme and get compiled CSS! Hooray progress! Any changes in your assets/sass directory should be included in the compiled CSS. This also means you can add SASS partials in the folder, include them in the style.scss file you created, and create a lavish ecosystem of overridden styles for your new theme.
To see your newly compiled styles in action, be sure to clear your caches by running
drush cache-rebuild, or if you don’t have drush installed visit
/admin/config/development/performance on your site and clear caches there.
You may also want to go ahead and disable CSS and JS caching while on that page during development.
Now refresh your homepage and see your styles in action!
It’s a little bare and it’s clear that some of the menu styles are still not 100%, but you’ll be able to handle those minor issues with no problems now that you have SASS in place on your Drupal 8 Bootstrap theme.
- 2018-02-01 – Created new guide for using the SASS starterkit and linked in header. It can be found here: Use the SASS Starterkit to Build a Drupal 8 Bootstrap Subtheme.
- 2016-11-15 – Fixed the formatting on the code blocks and added info about the release of the SASS starterkit in the Bootstrap theme.