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.
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:
1 composer require drupal/bootstrap
For the remainder of the article, I’m going to assume that the Bootstrap theme has been installed in the Drupal-project Composer default
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:
1 MACHINENAME=dropmix 2 FULLNAME="DropMix"
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
machinename appear replace them with your own full theme name and theme machine name respectively:
- In the new theme’s base directory, rename
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
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
- Last time in the new theme’s base directory, rename
- Inside the theme, go to
- Finally, in the theme go to
machinename.schema.yml. You’ll also need to open this file and replace the value
If following along in bash, you can run the following commands from the
1 cp -r contrib/bootstrap/starterkits/sass $MACHINENAME 2 cd $MACHINENAME 3 mv THEMENAME.starterkit.yml $MACHINENAME.info.yml 4 sed -i.bak "s/THEMETITLE/$FULLNAME/g" $MACHINENAME.info.yml && rm $MACHINENAME.info.yml.bak 5 sed -i.bak "s/THEMENAME/$MACHINENAME/g" $MACHINENAME.info.yml && rm $MACHINENAME.info.yml.bak 6 mv THEMENAME.libraries.yml $MACHINENAME.libraries.yml 7 mv THEMENAME.theme $MACHINENAME.theme 8 mv config/install/THEMENAME.settings.yml config/install/$MACHINENAME.settings.yml 9 mv config/schema/THEMENAME.schema.yml config/schema/$MACHINENAME.schema.yml 10 sed -i.bak "s/THEMETITLE/$FULLNAME/g" config/schema/$MACHINENAME.schema.yml && rm config/schema/$MACHINENAME.schema.yml.bak 11 sed -i.bak "s/THEMENAME/$MACHINENAME/g" config/schema/$MACHINENAME.schema.yml && rm config/schema/$MACHINENAME.schema.yml.bak
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
lib should reside just inside your new
You can do all this in CLI using the following commands:
1 mkdir bootstrap 2 curl -sL bootstrap-sass.tar.gz https://github.com/twbs/bootstrap-sass/archive/3.3-stable.tar.gz | tar zxC bootstrap --strip 1
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/Gemfileinto the new theme’s base directory.
- Copy and rename the file
bootstrap/bootstrap-sass.gemspecinto 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
../bootstrap/libto reflect the file’s new relative position.
Here are those changes for CLI:
1 cp bootstrap/Gemfile Gemfile 2 cp bootstrap/bootstrap-sass.gemspec $MACHINENAME.gemspec 3 sed -i.bak "s@../lib@../bootstrap/lib@g" $MACHINENAME.gemspec && rm $MACHINENAME.gemspec.bak
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:
1 bundle install 2 bundle exec compass init --sass-dir scss --css-dir css 3 bundle exec compass compile
Note that we define the
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.
1 bash -c ' 2 MACHINENAME=dropmix 3 FULLNAME="DropMix" 4 composer require drupal/bootstrap 5 cp -r themes/contrib/bootstrap/starterkits/sass themes/$MACHINENAME 6 cd themes/$MACHINENAME 7 mv THEMENAME.starterkit.yml $MACHINENAME.info.yml 8 sed -i.bak "s/THEMETITLE/$FULLNAME/g" $MACHINENAME.info.yml && rm $MACHINENAME.info.yml.bak 9 sed -i.bak "s/THEMENAME/$MACHINENAME/g" $MACHINENAME.info.yml && rm $MACHINENAME.info.yml.bak 10 mv THEMENAME.libraries.yml $MACHINENAME.libraries.yml 11 mv THEMENAME.theme $MACHINENAME.theme 12 mv config/install/THEMENAME.settings.yml config/install/$MACHINENAME.settings.yml 13 mv config/schema/THEMENAME.schema.yml config/schema/$MACHINENAME.schema.yml 14 sed -i.bak "s/THEMETITLE/$FULLNAME/g" config/schema/$MACHINENAME.schema.yml && rm config/schema/$MACHINENAME.schema.yml.bak 15 sed -i.bak "s/THEMENAME/$MACHINENAME/g" config/schema/$MACHINENAME.schema.yml && rm config/schema/$MACHINENAME.schema.yml.bak 16 mkdir bootstrap 17 curl -sL bootstrap-sass.tar.gz https://github.com/twbs/bootstrap-sass/archive/3.3-stable.tar.gz | tar zxC bootstrap --strip 1 18 cp bootstrap/Gemfile Gemfile 19 cp bootstrap/bootstrap-sass.gemspec $MACHINENAME.gemspec 20 sed -i.bak "s@../lib@../bootstrap/lib@g" $MACHINENAME.gemspec && rm $MACHINENAME.gemspec.bak 21 bundle install 22 bundle exec compass init --sass-dir scss --css-dir css 23 bundle exec compass compile 24 '