How to Add Bootstrap 5 Sass to Jekyll
Intro
The static site generator Jekyll allows you to add Bootstrap 5 in different ways. The easiest way is to use the precompiled CSS and JavaScript bundles, as described in my previous article. Alternatively you can use Bootstrap’s Sass and JavaScript source files and compile them by your own. Bootstrap’s Sass files contain many maps, mixins and other features that you can take advantage of. Adding and using these files in Jekyll is relatively is easy, since Jekyll comes with a built-in Sass compiler.
In This Guide
A clean Jekyll project is set up to generate static websites. The setup will be ready to compile Sass and add vendor specific CSS prefixes by integrating the autoprefixer plugin. Subsequently you will learn how to add the Sass source files of Bootstrap 5.1.3 to your Jekyll project. The first way is to simply import all of the Sass source files. The second way is to import only the source files that belong to the components you are working with.
Prerequisites
- Basic understanding of how Jekyll works
- Ruby version 3.0.0 or higher, as well as Jekyll and bundler gems installed on your machine
Clean Setup
New Project
Open your terminal at the desired working directory, create a new Gemfile with
bundle initand add the required Jekyll and WEBrick gems to the Gemfile
bundle add jekyll webrickLayout
In the project root directory create a _layouts folder. In that folder create a reusable layout file called default.html with the following content:
This basic layout file links the main.css stylesheet in the head section. This file will be located in the assets/css/ directory and will include both, the Bootstrap 5 CSS and the custom CSS. The body includes a nav.html partial which will hold a Bootstrap 5 navigation bar. The {{ content }}placeholder will be replaced by the content of a page during the build process. Before the closing <body> element, a minified version of the Bootstrap 5 JavaScript is linked, because some elements of Bootstrap rely on JavaScript to work properly. Since this guide is about the implementation of Sass, we use a CDN to fetch the JavaScript. The <script> tag above is taken from the Bootstrap documentation. For more information about how to use Bootstrap's JavaScript in your Jekyll project, check my previous article.
First Page
In the project root directory create a file index.html with the following content (alternatively you can use a Markdown file):
In the front matter at the top of this file, a layout is defined that will be used to render the content. The body content simply consists of <h1> header within a <div>. This content will be rendered in to the <main> element within the default.html file.
Navigation Bar
To illustrate whether Bootstrap is embedded correctly at the end of this guide, a standard navigation bar from the Bootstrap documentation is used. In your project root directory create a folder _includes. Inside _includes/ create a nav.html file with the following content :
The navigation bar requires both to work properly, Bootstrap’s stylesheets and JavaScript.
Styling
The styling of a website is often split into multiple files which must be compiled and bundled before deployment. Jekyll can compile and bundle multiple Sass files into a single CSS file by default. It expects the Sass files to be located in the _sass/ directory. Therefore, create a new folder _sass in your project root directory. Inside _sass/ create a new file base.scss which contains a basic styling for the content of a page, i.e. the content that is rendered into the <main> element of the default.html file.
Add the following to base.scss:
In your project root directory create a new folder assets. Inside assets/ create another folder css. Now create a new file main.scss inside assets/css/ with the following content:
This file serves as the entry point for the website’s styling and imports all other Sass files located in _sass. Since _sass/ is the default location for the Sass files, it is sufficient to state the name of the file ( base) as the import value without a potential underscore, rather than the complete path.
By default, all files inside assets/ will be copied to the _site folder during the build process. In addition to that, the Sass files must be compiled to CSS. The two dashed lines (empty front matter) at the beginning of main.scss signal Jekyll to compile them, rather than simply copying the files. The two dashed lines are only required in the first Sass file.
Note: In main.scss you can import as many Sass files from the _sass/ directory as you want. For simplicity, we limit to a single file.
Autoprefixer
As stated in the documentation, using Bootstrap’s Sass source files requires a compiler to compile them to CSS files and an autoprefixer for adding vendor specific CSS prefixes. While Jekyll comes with a built-in Sass compiler, it does not provide CSS prefixing. One easy way to solve that problem is by installing the jekyll-autoprefixer gem as a plugin.
Add the jekyll-autoprefixer gem to the Gemfile with
bundle add jekyll-autoprefixerIn addition add ExecJS in the version 2.7 if you face an error during the build process (see this GitHub Issue)
bundle add execjs -v 2.7To enable the plugin create a _config.yml file in the project root directory with the following content:
The first two lines activate the autoprefixer plugin. The plugin can then be configured under the autoprefixer keyword. In our case we simply want prefixes to support the last four versions of each browser.
That’s Our Base Setup
The Jekyll project now has the following structure:
/
_includes/
nav.html
_layouts/
default.html
_sass/
base.scss
assets/
css/
main.scss
_config.yml
Gemfile
index.htmlBuild the project with
bundle exec jekyll serveand browse http://127.0.0.1:4000.
The website now consists of the navigation bar from Bootstrap and the content from the index.html file. As you can see, the styling from base.scss is applied to the content of index.html, which indicates that Sass files are correctly processed and linked.
If you add Safari > 2 to the list of browsers in the autoprefixer configuration and rebuild the project, main.css contains a new line -webkit-border-radius: 8px;. This is because the CSS property border-radius only works in Safari version 3 to 5 with the -webkit prefix. Safari > 2 signals the the autoprefixer to add the -webkit prefix to each CSS property that is not fully supported in any Safari version > 2. This verifies that the plugin is implemented correctly.
This setup serves as a base for the upcoming parts.
Source Code
GitHub: Jekyll Base Setup
Download Bootstrap 5
Downloaded Bootstrap 5 from the download page, by clicking the Download source button in the Source files section. Then unzip the bootstrap-5.1.3 folder after the download.
Add Source Files to Jekyll
In the _sass/ directory create a new folder bootstrap. This folder will contain all of Bootstrap's Sass source files, separated from our custom Sass file. bootstrap-5.1.3/scss/ contains the necessary Sass files. Copy all of them in to _sass/bootstrap/ of your Jekyll project.
The Jekyll project now has the following structure:
/
_includes/
nav.html
_layouts/
default.html
_sass/
base.scss
assets/
css/
bootstrap/
forms/
...
helpers/
...
mixins/
...
utilities/
...
vendor/
...
...
bootstrap.scss
bootstrap-grid.scss
bootstrap-reboot.scss
bootstrap-utilities.scss
main.scss
_config.yml
Gemfile
Gemfile.lock
index.htmlOption 1: Embed All of Bootstrap’s Sass
The easiest way to use the Bootstrap Sass source files within Jekyll is by importing bootstrap.scss from _sass/bootstrap/ at the top of our Sass entry file main.scss in the assets/css/ folder. bootstrap.scss in turn imports all the remaining Sass files from Bootstrap in the correct order. The updated main.scss file now looks as follows:
Since Bootstrap’s Sass files are located in the subfolder bootstrap/, the path relative to the _sass directory must be prepended to the filename. Bootstrap must be imported before the custom styles. Otherwise the build process will fail.
At this point, Bootstrap’s Sass files are already embedded in Jekyll. When rebuilding the project, a default Bootstrap style will be applied to the navigation bar. To verify that Bootstrap’s variables, mixins and other features can be used in the custom base.scss file, override the Bootstrap's $primary variable with a new color and apply it to the <h1> element and set the background color to $secondary:
Rebuild the project with
bundle exec jekyll serveand browse http://127.0.0.1:
As you can see, the default Bootstrap styling is applied to the navigation bar. Also while the default secondary color is applied to the background of <h1>, the primary color is successfully overridden and applied to the font color.
Source Code
GitHub: Jekyll with Bootstrap 5 Sass — Option 1
Option 2: Embed Bootstrap Sass Selectively
Instead of importing all Bootstrap Sass files, you can import only the files you really need. In this case, the order of the imports matters. Revert potential changes from Option 1. Modify the main.scss file according to the structure from the Bootstrap documentation:
The first file that must be imported is functions.scss which is required to process the source code properly. In the second step Bootstrap's default variables can be overridden before importing them in a third step. If you work with Bootstrap for the first time this may look weird but Bootstrap process the modifications correctly as long as you import _functions.scss at the beginning.
To verify that Bootstrap is embedded correctly at the end of this guide, simply override the primary color. After the default variables Bootstrap’s mixins and a root script for generating :root CSS variables must be imported.
In step four you can selectively import the required source files. Since some source files depend on others it can be tricky to determine which one you need. In the example above the files listed under 4. and 5. are required for the default navigation bar to have the same look and behavior as with Option 1. At the end you can import the remaining custom Sass files.
Apply the modified primary color to the font of <h1> and set Bootstrap's default secondary color for the background. The modified base.scss file looks as follows:
Rebuild the project with
bundle exec jekyll serveand browse http://127.0.0.1.
The navigation bar now has the same appearance and behavior as in Option 1. Also, Bootstrap’s primary color is overridden and applied which verifies that Bootstrap is embedded correctly.
Source Code
GitHub: Jekyll with Bootstrap 5 Sass — Option 2
Summary
We built a clean Jekyll setup that includes the jekyll-autoprefixer gem for adding vendor specific CSS prefixes. Then we downloaded Bootstrap 5.1.3 and subsequently added the Sass source files in two different ways. The first ways was to import the main bootstrap stylesheet, which in turn imports the remaining files. The second way was to import only the Sass files of the components we are working with.
Thank your for reading :)
