How to Add Bootstrap 5 to Jekyll in Two Easy Ways
Intro
Jekyll is a great framework to build static websites. By default it allows you to split your source code into smaller units and compiles them to clean HTML, CSS and JavaScript files. It also allows you to embed CSS and JavaScript frameworks in different ways. One of the most widely used frameworks is Bootstrap, currently in version 5.1.3. However, when working with Jekyll and Bootstrap for the first time, you might face some unexpected problems when embedding Bootstrap in your Jekyll project.
In This Guide
A clean Jekyll project is created at the beginning. Subsequently Bootstrap 5.1.3 is added in two simple ways. First by fetching Bootstrap’s bundled CSS and JavaScript files from a CDN. Second by embedding the CSS and JavaScript bundles in Jekyll and fetching them from the web server.
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 and create a new Gemfile with
bundle initThen add the required Jekyll and WEBrick gems to the Gemfile
bundle add jekyll webrickFirst Page
In your project root directory create a index.html file (alternatively you can use a Markdown file) with the following content:
Jekyll will use the content of this file to build the website’s index.html file. At the top we define the layout as front matter which tells Jekyll how to render the content of this page.
Layout
Next, create a folder _layouts in the project root directory. In that folder create a reusable layout file called layout.html with the following content:
The stylesheet is linked in the head section. The document’s body includes the nav.html, which will hold the HTML for the navigation bar, as well as the JavaScript file before the closing <body> element. The CSS and JavaScript files will be created later in the assets/ folder, which will be copied during build time. {{content}} is a placeholder for the content of a page. In case of the index.html file, {{content}} will be replaced during build with
Navigation Bar
We we will create a navigation bar to illustrate whether Bootstrap is embedded correctly. In the project root directory create a new folder _includes. In that folder create a nav.html file with the following example code from Bootstrap:
The code above requires both, Bootstrap’s CSS and JavaScript to work properly.
Styling
Create a assets folder in the project root director. All files and folders inside assets/ will be copied during the build process. Inside assets/ create another folder css. In this folder create styles.scss which will serve as the entry point for the website’s CSS. We will use a Sass file instead of a CSS file for greater flexibility.
styles.scss
The two dashed lines (empty front matter) at the beginning of the file are mandatory and indicate Jekyll to process the file rather than simply copying it. Note: The empty front matter is only mandatory in the first Sass file!
The main purpose of styles.scss is to import other files which will hold the styles for different parts of the website. By default, Jekyll expects the imported Sass files to be located in _sass/`. Therefore, it is sufficient to indicate only the file name, base, as the @import value rather than the complete path.
Now create the folder _sass in the project root directory. Inside _sass/ create a base.scss file with some basic styling for the content:
This basic styling is applied to the content of the index.html file to verify that the CSS is properly loaded.
JavaScript
In the assets/ directory create a folder js for the JavaScript files. In that folder create main.js with the following code:
This script simply logs Page loaded. to the console to verify that JavaScript is properly loaded.
Result
The Jekyll project now has the following structure:
/
_includes/
nav.html
_layouts/
default.html
_sass/
base.scss
assets/
css/
styles.scss
js/
main.js
Gemfile
index.htmlBuild the project with
bundle exec jekyll serveand browse http://127.0.0.1:4000.
The custom CSS and JavaScript is embedded correctly, as you can see in the browser`s console and by the applied styling for the content. Since Bootstrap is not embedded yet, the navigation bar is missing any styling.
Source Code
GitHub: Clean Jekyll setup
Option 1: Fetch Bootstrap 5 From a Content Delivery Network
The easiest way to add Bootstrap in Jekyll is by fetching Bootstrap’s bundled CSS and JavaScript files from a Content Delivery Network (CDN). A CDN is a distributed server network that vendors use to deliver various contents.
Implementation
All we need to do is adding a <link> and a <script> element to the layout file that refers to the CDN.
The Bootstrap documentation provides the relevant code snippets with references to the jsDelivr CDN.
Add the following snippet to the head section right before we link our custom CSS:
To import Bootstrap’s JavaScript we add the following snippet right before we link our custom JavaScript:
The browser will then fetch a bundled CSS and JavaScript version of Bootstrap 5.1.3 from the CDN.
It is important to set the <link> and <script> elements from Bootstrap before those of the custom CSS and JavaScript files. Otherwise you might face problems when using Bootstrap in your custom CSS and JavaScript.
Result
The updated layout.html file now looks as follows:
Rebuild the project with
bundle exec jekyll serveand browse http://127.0.0.1:4000.
As you can see, the default Bootstrap styling has been applied to the navigation bar. When clicking on Dropdown, a submenu appears which indicates that Bootstrap’s JavaScript is correctly embedded as well.
Source Code
GitHub: Jekyll with Bootstrap 5 — Option 1
Option 2: Add Bootstrap 5 Bundles to Jekyll
An alternativ is to download and copy Bootstrap’s CSS and JavaScript bundles to the assets/ directory and host them with the remaining files of the website on the web server. The browser will then fetch the CSS and JavaScript bundles from the web server rather than a CDN.
Download Bundles
Bootstrap provides different download options. On the download page for Bootstrap 5.1, click on Download in the Compiled CSS and JS section pretty much at the beginning of the page and unzip the downloaded bootstrap-5.1.3-dist folder.
Implementation
The downloaded folder provides different compiled CSS and JavaScript bundles. The easiest way to embed the Bootstrap CSS is by copying bootstrap.min.css and bootstrap.min.css.map from the css/ folder to the assets/css/ directory of the Jekyll project. bootstrap.min.css is the compiled and minified version of the complete Bootstrap CSS, whereas bootstrap.min.css.map is a source map that maps the minified CSS back to the original source files. Usually source maps are used during development. If you don’t need it, remove the source map file and the link at the end of bootstrap.min.css.
Similarly to the CSS, copy bootstrap.bundle.min.js and bootstrap.bundle.min.js.map from the downloaded js/ folder in to assets/js/ of the Jekyll project. Compared to bootstrap.min.js bootstrap.bundle.min.js includes the third party library Popper.js, which is required by some Bootstrap plugins. Again, bootstrap.bundle.min.js.map maps the minified JavaScript version to the original source code and is primarily used for development purposes. If you don’t need it, remove the source map file and the linkt at the end of bootstrap.bundle.min.js.
Now embed Bootstrap by adding <link> and <script> elements in the default.html layout file. Since the assets/ folder is copied as is during build, the reference of each element points to the corresponding Bootstrap file within the assets/ folder.
Add the following <link> element to the document’s head section before the custom CSS. Otherwise Bootstrap’s CSS classes cannot be overridden in the custom CSS:
The <script> element for Bootstrap’s Javascript must be added before the custom JavaScript in the default.html layout file. Otherwise you might face problems when using it in your custom CSS.
Result
The default.html file now looks as follows:
The Jekyll project now has the following structure:
/
_includes/
nav.html
_layouts/
default.html
_sass/
base.scss
assets/
css/
bootstrap.min.css
bootstrap.min.css
styles.scss
js/
bootstrap.bundle.min.js
bootstrap.bundle.min.js.map
main.js
Gemfile
index.htmlRebuild the project with
bundle exec jekyll serveand browse http://127.0.0.1:4000.
As you can see, the default Bootstrap styling has been applied to the navigation bar. When clicking on *Dropdown*, a submenu appears, which indicates that Bootstrap’s JavaScript is correctly embedded as well.
After building for production with `bundle exec build`, the Bootstrap bundles are copied with the remaining files of the website to the `_site` folder. This folder can be uploaded as is to your web server. The browser will then fetch the bundles from your web server rather than a CDN as in Option 1.
Source Code
GitHub: Jekyll with Bootstrap 5 — Option 2
Summary
In this guide we built a clean Jekyll setup and subsequently added Bootstrap 5 in two easy ways. First by fetching the bundled CSS and JavaScript files from a CDN. Second by copying the downloaded CSS and JavaScript bundles to the project which are then uploaded to the web server.
Thank you for reading :)
