How to build bootstrap css with jekyll?


tl;dr: How to build a custom bootstrap with jekyll?

I utilize bootstrap 5 for most of my websites. (
Bootstrap is a CSS framework that makes it easier to make a pretty, responsive website.

In a nutshell, it works by including a CSS file on my website that then provides a lot of pre-defined CSS classes that I can utilize.

This works very well except for one problem: the included CSS file is quite big - almost 30 kb.
I would like to slim that down to less than 15 kb.

The reason bootstrap.css is 30kb is that it contains a lot of classes, variables, etc. for all kinds of things which I do not need.
Fortunately, the bootstrap people thought about this and made it possible to build a custom CSS file using Sass (Sass · Bootstrap v5.3)
This way, I can build my own custom bootstrap.css that only contains the classes that I utilize and skip the rest.

Since Jekyll comes with a Sass compiler I thought it would be easy to just put the .scss files from bootstrap into my _sass folder in my jekyll site and have jekyll compile it.
However, this proved more difficult than I imagined.

I hope to hear from someone who has managed to build a custom bootstrap with jekyll.
How did you do it?

I don’t think it is that easy to do - I think you need to be able to have a build tool run some commands to build out the css with just the things needed - but it is probably using the full css when doing dev locally?

I’ve not seen any posts about how to do this type of thing with BS - though Tailwind is similar and I have seen posts about that - and there was a fair amount of setup to do it, looked like a bit of a pain.

If you google remove unused css jekyll I think you might find some easier solutions where you could just use the full BS css and then run a command to strip it down to what you need when you build for production, probably similar to the way BS wants you to do it but sort of manually triggered?

Another idea might be to separate out the css/assets from your project and have jekyll just do the layouts/includes/markdown stuff. I used to do this using gulp and then npm and it worked well but was a little complicated.

Hi there, I feel like I am only answering 1/2 of your question, but since I only know one method, I thought this could at least get you started.

There are two ways to access Bootstrap for any site:

  1. Connect to the CDN, which means your website will connect to an external source to connect to the Bootstrap components. This is the easiest method; you can jump into it immediately with Jekyll.
  2. Download the Bootstrap components and use them on your website. This may include a one-time download, modifications to the default Minima site, and more.

I know how to do #1, and it is easy. I will assume you are starting with Jekyll’s default minima theme. I suggest you do as well to verify you get the right results. Once you know what you are doing, go ahead and continue modifying the Minima site, create a site from scratch, or play around with other Jekyll themes.

  1. Override your theme
  2. Among other things, you will now have two new folders: _includes and _layouts
  3. Edit the _includes/head.html file, follow this link. Copy the <!-- Required meta tags --> and <!-- Bootstrap CSS --> elements and paste them into the <head> section of your head.html file.

Note: You must delete the existing utf-8 and viewport lines; more on that viewport line in a moment!

  1. Save head.html
  2. Open the _layouts/default.html and paste the JavaScript you want to use just above the </body> tag. Nothing else should be between the Bootstrap code and that </body> tag. Use the same Bootstrap link from #3 above. I usually copy the line under <!-- Option 1: Bootstrap Bundle with Popper --> and paste that into the default.html file.
  3. Save the default.html file
  4. To test that Bootstrap works, edit the / file and add the sample code to build a navigation bar.
  5. Save index.html
  6. You are done adding Bootstrap, and you can run bundle exec jekyll serve --livereload to see the results, but please read on for more details…

Bootstrap and Minima

Jekyll’s default Minima has custom CSS or SASS/SCSS, like many themes. It is much easier to start from scratch using Bootstrap components.

However, if you want to use the Minima theme and play around with a pre-built site, please see the attached screenshots. Part of setting up Bootstrap was to change the meta viewport, which includes settings incompatible with the Minima theme.

It is easy to fix because you will probably replace the website header with Bootstrap navbar and nav- components. The footer will look a little broken with the columnar layout, but you can easily replace that with the grid systen using <section> and the row and col classes.

Next steps

After you are comfortable using Bootstrap with Jekyll, you can move on to adding the files directly to your site, but you probably want to manage the installation of those files for version control. If so, you will probably want to switch to Docker. While I create a video that shows you how to use Docker with GitHub Pages, I have not gone through the process of

Actually what you want to achieve is not done by sass compilers. It must be done by another tool, like UnCSS or PurgeCSS. These tools analyze your stylesheet and discard from it any classes that are not being used.

I used PurgeCSS in a template site that I am currently a maintainer. This was done in 2 steps:

  1. Created purgecss.config.js with all the rules that will be used to clean the stylesheet, which in our case is:
module.exports = {
  content: ["_site/**/*.html", "_site/**/*.js"],
  css: ["_site/assets/css/*.css"],
  output: "_site/assets/css/",
  skippedContentGlobs: ["_site/assets/**/*.html"],
  1. Added a step in our GitHub action responsible for building and deploying the site to install and call PurgeCSS:
    runs-on: ubuntu-latest
      # steps to download and build the site first
      - name: Purge unused CSS 🧹
        run: |
          npm install -g purgecss
          purgecss -c purgecss.config.js
      # steps to deploy site

At the time I implemented this I got the following reduction is css sizes:

current minify PurgeCSS PurgeCSS + minify
1,1M 988K 456K 420K

I think this might be a good approach: to discard things from bootstrap.css that are not utilized.

However, I am a bit hesitant to proceed with anything in which the instructions start with “npm install …”
I currently do not use node.js in any projects and to be honest, I don’t quite understand what it is… But I am a bit afraid of introducing some huge dependency.

Are there no standalone tools that will do something similar to UnCSS or PurgeCSS that are just a static compiled binary or perhaps a python script?

Or are my concerns about node.js/npm unwarranted?

Are there no standalone tools that will do something similar to UnCSS or PurgeCSS that are just a static compiled binary or perhaps a python script?

I am not aware of any.

Or are my concerns about node.js/npm unwarranted?

It depends. You are working with some web technology, and sometimes they can get intertwined. And you can benefit from both.

Also npm is something like pip for python, used to install packages and libraries, and sometimes these packages can run as a standalone. For example, if you install tqdm in python, it can be run as a standalone, even though it was installed via pip. The same is true for npm.

If you look at the GitHub action above, after installing PurgeCSS with npm I simply run it with purgecss -c purgecss.config.js. So, I understand your concern about adding too much dependencies, but since this is just another step in a build process that can run in a remote isolated machine, I think it is not much trouble.