Using Bootstrap CSS with Jekyll

(updated )

There are multiple ways to integrate Bootstrap with Jekyll. This article documents how I did it for my site which runs on Github pages (which means that I have the constraint that I can’t use Jekyll plugins) and only uses Bootstrap CSS.

Bootstrap CSS is written using Less, but Jekyll has integrated support for Sass. Fortunately, there is an official Sass port of Bootstrap, and I’m using this for my site.

Here are the basic steps to integrate the Sass port into your Jekyll site:

  1. Download the archive for the latest version at https://github.com/twbs/bootstrap-sass/tags. Alternatively, clone the git repository and checkout the tag for the latest version.

  2. Copy the following files and directories from the archive to the Sass directory of your Jekyll project (which is _sass unless you have configured a different directory in _config.yml):

    • assets/stylesheets/_bootstrap.scss

    • assets/stylesheets/bootstrap

    If you need glyphicons, also copy the assets/fonts directory to the root of your Jekyll project.

  3. Create a basic stylesheet (e.g. styles/site.scss) as follows:

    ---
---
    
@import "bootstrap";

    The two --- lines at the beginning instruct Jekyll to process the file using Sass (resulting in a styles/site.css file) instead of copying it verbatim to the generated site. The @import directive will include _sass/_bootstrap.scss, which in turn includes all the Bootstrap CSS components (under _sass/bootstrap).

  4. Ensure that all layouts for which you will use your new stylesheet have the recommended doctype and viewport meta tag as described in the Bootstrap documentation.

You can now start to customize Bootstrap. Here are a few things that you might want to consider:

  • The Bootstrap CSS can be customized using variables. These variables and their default values are defined in _sass/bootstrap/_variables.scss. I don’t recommend to change this file because this would make upgrading to a new Bootstrap version more difficult. Instead you should override these variables in styles/site.scss, as shown in the following example:

    ---
---
    
$font-size-base: 17px;
$headings-font-weight: 600;
$blockquote-font-size: $font-size-base;
    
@import "bootstrap";

    If you plan to create additional stylesheets, chances are high that you want to reuse these variables. In that case it is better to define them in a separate file, e.g. _sass/_variables.scss:

    $font-size-base: 17px;
$headings-font-weight: 600;
$blockquote-font-size: $font-size-base;
    
@import "bootstrap/variables";

    The purpose of the import at the end of the file is to ensure that all variables are defined, even the ones that are not explicitly overridden.

    Your styles/site.scss file should then look as follows:

    ---
---
    
@import "variables";
@import "bootstrap";

    Note that this will indirectly import _sass/bootstrap/_variables.scss twice (once via _sass/_variables.scss and once via _sass/_bootstrap.scss), but that is not an issue because that Sass file only sets variables that have not been defined before, which means that the second import will have no effect.

    With that in place, you can reuse the variables in other stylesheets:

    ---
---
    
@import "variables";

.tag-cloud span { 
  font-size: 0.7*$font-size-base;
  vertical-align: super
}

  • The stylesheet generated by Sass will be quite large. To reduce its size you may want to enable compression by adding the following option to your _config.yml file:

    sass:
    style: :compressed

  • By importing _sass/_bootstrap.scss, you will include all the Bootstrap CSS components into the stylesheet. However, it is unlikely that you use all of them. You may want to further reduce the size of the resulting stylesheet by importing only the components you need, as in the following example:

    ---
---
    
@import "variables";
    
@import "bootstrap/mixins";
@import "bootstrap/normalize";
@import "bootstrap/print";
@import "bootstrap/scaffolding";
@import "bootstrap/type";
@import "bootstrap/grid";
@import "bootstrap/responsive-utilities";

References

As noted in the introduction, there are many ways to integrate Bootstrap with Jekyll. Here is a selection of other artiles and projects on that subject: