Robin Klöckner
Robin Klöckner

Robin Klöckner

Two Easy Ways To Add Bootstrap 5.1 in Jekyll

Two Easy Ways To Add Bootstrap 5.1 in Jekyll

A beginner's guide

Robin Klöckner's photo
Robin Klöckner
·Jun 11, 2022·

9 min read

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 init

Then add the required Jekyll and WEBrick gems to the Gemfile

bundle add jekyll webrick

First Page

In your project root directory create a index.html file (alternatively you can use a Markdown file) with the following content:

---
layout: default
---
<div>
  <h1>Embedding Bootstrap 5 in Jekyll</h1>
</div>

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:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Title</title>
  <link rel="stylesheet" href="/assets/css/styles.css">
</head>
<body>
  {% include nav.html %}
  <main>
    {{ content }}
  </main>
  <script src="/assets/js/main.js"></script>
</body>
</html>

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

<div>
  <h1>Embedding Bootstrap 5 in Jekyll</h1>
</div>

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:

<nav class="navbar navbar-expand-lg navbar-light bg-light">
  <div class="container-fluid">
    <a class="navbar-brand" href="#">Navbar</a>
    <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbarSupportedContent" aria-controls="navbarSupportedContent" aria-expanded="false" aria-label="Toggle navigation">
      <span class="navbar-toggler-icon"></span>
    </button>
    <div class="collapse navbar-collapse" id="navbarSupportedContent">
      <ul class="navbar-nav me-auto mb-2 mb-lg-0">
        <li class="nav-item">
          <a class="nav-link active" aria-current="page" href="#">Home</a>
        </li>
        <li class="nav-item">
          <a class="nav-link" href="#">Link</a>
        </li>
        <li class="nav-item dropdown">
          <a class="nav-link dropdown-toggle" href="#" id="navbarDropdown" role="button" data-bs-toggle="dropdown" aria-expanded="false">
            Dropdown
          </a>
          <ul class="dropdown-menu" aria-labelledby="navbarDropdown">
            <li><a class="dropdown-item" href="#">Action</a></li>
            <li><a class="dropdown-item" href="#">Another action</a></li>
            <li><hr class="dropdown-divider"></li>
            <li><a class="dropdown-item" href="#">Something else here</a></li>
          </ul>
        </li>
        <li class="nav-item">
          <a class="nav-link disabled">Disabled</a>
        </li>
      </ul>
      <form class="d-flex">
        <input class="form-control me-2" type="search" placeholder="Search" aria-label="Search">
        <button class="btn btn-outline-success" type="submit">Search</button>
      </form>
    </div>
  </div>
</nav>

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

---
---
@import "base";

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:

body {
  width: 100%;
  height: 100vh;
  margin: 0;
  padding: 0;
  font-family: Arial, system-ui;
}

main > div {
  height: 10rem;
  margin: 2rem;
  border: darkgrey 1px solid;
  border-radius: 8px;
  overflow: hidden;
}

h1 {
  text-align: center;
  color: gray;
}

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:

window.addEventListener('load', (event) => {
  console.log("Page loaded.");
});

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.html

Build the project with

bundle exec jekyll serve

and browse http://127.0.0.1:4000.

00_base.png

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:

<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.1.3/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-1BmE4kWBq78iYhFldvKuhfTAU6auU8tT94WrHftjDbrCEXSU1oBoqyl2QvZ6jIW3" crossorigin="anonymous">

To import Bootstrap's JavaScript we add the following snippet right before we link our custom JavaScript:

<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.1.3/dist/js/bootstrap.bundle.min.js" integrity="sha384-ka7Sk0Gln4gmtz2MlQnikT1wXgYsOg+OMhuP+IlRH9sENBO0LRn5q+8nbTov4+1p" crossorigin="anonymous"></script>

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:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Title</title>
  <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.1.3/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-1BmE4kWBq78iYhFldvKuhfTAU6auU8tT94WrHftjDbrCEXSU1oBoqyl2QvZ6jIW3" crossorigin="anonymous">
  <link rel="stylesheet" href="/assets/css/styles.css">
</head>
<body>
  {% include nav.html %}
  <main>
    {{ content }}
  </main>
  <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.1.3/dist/js/bootstrap.bundle.min.js" integrity="sha384-ka7Sk0Gln4gmtz2MlQnikT1wXgYsOg+OMhuP+IlRH9sENBO0LRn5q+8nbTov4+1p" crossorigin="anonymous"></script>
  <script src="/assets/js/main.js"></script>
</body>
</html>

Rebuild the project with

bundle exec jekyll serve

and browse http://127.0.0.1:4000.

01_cdn.png

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.

bootstrap.jpg

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:

  <link rel="stylesheet" href="/assets/css/bootstrap.min.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.

  <script src="/assets/js/bootstrap.min.js"></script>

Result

The default.html file now looks as follows:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Title</title>
  <link rel="stylesheet" href="/assets/css/bootstrap.min.css">
  <link rel="stylesheet" href="/assets/css/styles.css">
</head>
<body>
  {% include nav.html %}
  <main>
    {{ content }}
  </main>
  <script src="/assets/js/bootstrap.bundle.min.js"></script>
  <script src="/assets/js/main.js"></script>
</body>
</html>

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.html

Rebuild the project with

bundle exec jekyll serve

and browse http://127.0.0.1:4000.

02_webserver.png

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 :)

 
Share this