Use the SASS Starterkit to Build a Drupal 8 Bootstrap Subtheme

So you want to build a Drupal 8 site with the Bootstrap theme. You still love the power SASS provides, so you’re excited when you hear that there’s a lovely SASS starterkit that accompanies the theme–that ought to get you going with a subtheme quickly. You get the Bootstrap theme in place, plop the subtheme out into its own directory, activate the subtheme, aaaaand…nothing. What gives?

This article will guide you through the process of properly setting up your new Drupal 8 Bootstrap SASS starterkit theme. It serves as a sequel to my original article from 2016 where we cannibalized a LESS starterkit. Most of this information can be found on the Drupal 8 Bootstrap Documentation Pages, but this guide adds a little more context and information about the process as well as some handy commands for your CLI.

Baseline Installation

This guide assumes you’ve already got a couple things in place:

• A working copy of Drupal 8
• Ruby with Bundler already installed and configured. Bootstrap SASS uses Bundler to version control Compass which is what we’ll use to compile the SASS.
• A copy of the Drupal 8 Bootstrap base theme already installed.

To get the base theme you can download it directly from the Drupal 8 Bootstrap project page, use Drush or Drupal Console to download it, or if your project is based on Composer (and it should be!) you can use it to install the theme:

For the remainder of the article, I’m going to assume that the Bootstrap theme has been installed in the Drupal-project Composer default DRUPALROOT/themes/contrib/bootstrap folder.

It’ll also be helpful to know at least a little command line on the system you’re working on (which really is kind of a prerequisite for compiling SASS for development anyways). The commands that I’m providing have been tested on Mac OSX High Sierra, and while I’ve tried to make them portable for Linux machines (looking at you, sed) I can’t guarantee they’re gonna work right out of the box for Linux or bash on Windows. Please leave a comment if you see success or have fixes for those environments!

Installing Drupal 8 Bootstrap with the SASS Starterkit

Step 0: Set some handy bash variables

If you’re going to be following along in CLI, it will be useful to set some variables so you can copy the commands in each step easily. So we’ll set up the machine name and the full name of the theme you’re going to create by setting some variables. Paste this into your shell, replacing the “DropMix” values with the name you want for the theme:

For this particular project I was making a fan site for the game DropMix. DropMix is a delightful card-based music game, totally worth checking out if you haven’t already!

Step 1: Make your custom theme based on the starterkit

Inside of the Drupal 8 Bootstrap theme is a folder labeled starterkits. You’ll want to copy the one labeled sass and paste it into the themes directory where you want it. Take this opportunity to rename the theme with your machine name as well. Make sure this machine name stays consistent throughout; it’s how Drupal will find key theme files.

With the starterkit copied over, it’s time to rename and clean up the values of some files so that Drupal 8 will recognize them as part of your theme. Where the values fullname and machinename appear replace them with your own full theme name and theme machine name respectively:

• In the new theme’s base directory, rename THEMENAME.starterkit.yml to machinename.info.yml. Drupal 8 will “see” your theme once this file is in place. You’ll also need to open this file and replace the value THEMETITLE with fullname and THEMENAME with machinename. Take the opportunity as well to make a custom description for your theme, though this is not required.
• Also in the new theme’s base directory, rename THEMENAME.libraries.yml to machinename.libraries.yml.
• Last time in the new theme’s base directory, rename THEMENAME.theme to machinename.theme.
• Inside the theme, go to config/install and rename THEMENAME.settings.yml to machinename.settings.yml.
• Finally, in the theme go to config/schema and rename THEMENAME.schema.yml to machinename.schema.yml. You’ll also need to open this file and replace the value THEMETITLE with fullname and THEMENAME with machinename.

If following along in bash, you can run the following commands from the DRUPALROOT/themes directory:

You can now turn your theme on in the system if you’d like. Navigate to /admin/appearance while logged in and scroll down to “Uninstalled themes.” Under your new custom theme click “Install and set as default” to enable it.

Note that this will also enable the Bootstrap theme as the parent theme.

When you venture back to the main site, it’ll look a little bare because we don’t actually have the SASS downloaded or compiled. Time to get all that in place!

Step 2: Get and place bootstrap assets

While the Drupal 8 Bootstrap theme SASS starterkit looks ready to go, it’s actually missing the core SASS files used to build the stylesheets. Navigate to the Bootstrap SASS Github repo to download the latest version of the official Bootstrap 3 SASS port.

With that downloaded, you’ll want to create a new directory in your theme called bootstrap and extract that Github repository into it. When you’re finished, folders like assets and lib should reside just inside your new bootstrap folder.

You can do all this in CLI using the following commands:

With Bootstrap SASS downloaded, we’ll want to use some files from it to make our lives a little easier when compiling our theme. We’ll be using Bundler to compile, and to do that we need to have a Gemfile in place. Fortunately Bootstrap SASS already comes with one pre-written, so let’s move some files to support that:

• Copy the file bootstrap/Gemfile into the new theme’s base directory.
• Copy and rename the file bootstrap/bootstrap-sass.gemspec into the new theme’s base directory and name it machinename.gemspec. You’ll also want to make a small change in the first line of the file, changing ../lib to ../bootstrap/lib to reflect the file’s new relative position.

Here are those changes for CLI:

Step 3: Compile!

With the Gemfile properly in place, we can use Bundler to install Compass. With Compass installed, we can create a config file by initializing a project, and from there we can compile the SASS any time we’d like! This part is 100% command line, so enter these lines while in the new theme’s base directory:

Note that we define the sass-dir and css-dir when initializing Compass to match the folder names already provided by the Drupal 8 Bootstrap SASS starterkit.

Your SASS-powered Drupal 8 Bootstrap Theme is Up and Running!

Your new site should have Bootstrap styles applied now!

Doesn’t look like much right now, but it’s clear that the Bootstrap styles are in place and available for you to use.

So what next?

Moving forward, you can run compass compile and compass watch to compile your SASS, but note that you’ll need to prefix them with bundle exec to get them to work consistently. In this way, Bundler maintains which gems are accessible across all the platforms this code is run on.

For custom code, you can make modifications to the MACHINENAME/scss/_overrides.scss file, but I’d recommend creating your own component files and including them in style.scss. Set up the file structure that works for you, and make changes to the Compass-generated config.rb when you need to change what folders files appear in.

Take It Live!

With your new theme in place, leveraging the rapid development of Bootstrap and the power of SASS, you should quickly be on your way to a complete design for your site. If you ever need help building or deploying your website, know that Sevaa Group is willing and able to help you. Just reach out to us and we’ll be on the job in a hurry!

Appendix: The Full CLI Script

If you just want the whole shebang in one paste, from installing the Drupal 8 Bootstrap theme with Composer to your first compass compile, you can use the following script. Note that the script is surrounded by quotes so that this set of commands can run sequentially, as the composer and curl commands in particular can take some time. Make sure you set the MACHINENAME and FULLNAME to the values you want before running this in Drupal’s root directory.