Starting with Bootstrap 4, building from the SASS source requires Autoprefixer. In this article I’ll show how I configured my Jekyll site to autoprefix the stylesheets and deployed this on Gitlab pages.
The easiest way to include Bootstrap’s source in your project is using Git Submodules. If you don’t have one already, create a
_sass folder at the root of your project and clone bootstrap into it:
$ git submodule add https://github.com/twbs/bootstrap.git
This will get the latest commit of Boostrap. Typically you want to use the latest release, so go to the releases page and get the tag name of the latest release. This is shown with a tag icon on the left-hand side.
For this release the tag name is
v4.1.1. Now check out this tag:
$ cd bootstrap $ git checkout v4.1.1
You know have the SASS source of the latest version of Bootstrap. Now we need to tell Jekyll to compile it, with our modifications, into CSS.
Including & Overriding
In the root of your Jekyll project, create a folder called
css. Create a file called
styles.scss with the following SCSS:
--- --- @import "main";
--- section (called front matter) tells Jekyll that it needs to process this file itself. This isn’t required in any other SCSS files because they’ll be processed by SASS.
_sass folder create an empty file called
variables.scss and a file called
main.scss containing this:
@import "variables"; @import "bootstrap/scss/bootstrap";
This will import any custom files we set in the variables file, then import Bootstrap itself. You can override anything in Bootstrap’s own variables file.
_config.yml file make sure the following properties are set:
sass: sass_dir: _sass style: compressed
This tells Jekyll that your SASS files are located in the
_sass directory and that it should minify the CSS it produces. However, this CSS will still be missing the prefixes that Bootstrap requires. To add these, we’ll need to use some additional gems.
Add the following gems to your
gem 'jekyll-autoprefixer' gem 'therubyracer'
therubyracer to configure the V8 interpreter (a high performance JS interpreter) to run this package.
Now we have to tell Jekyll about autoprefixer by adding it to the config file. Add
'jekyll-autoprefixer' to the
gems property. My gems property looks like this, you may not be using the other gems or you may have extra.
gems: - jekyll-feed - jekyll-seo-tag - jekyll-autoprefixer
We don’t need to register
therubyracer because Jekyll itself doesn’t actually use this package.
Deploying with Gitlab Pages
Jekyll will now autoprefix our CSS so Bootstrap will work properly. Unfortunately Github pages doesn’t support the necessary gems, so a different deployment method is required. It’s possible to host this yourself, but Gitlab offer a similar service that allows complete configuration of the deployment process.
Create a new file in the root of your site called
.gitlab-ci.yml. Paste this configuration into the file. There are a few important things in this file:
image:sets a base image for the CI to use. Any image from Docker Hub can be used.
variables:sets Jekyll to run in production mode
before_script:sets up the correct localisation (the build fails without this) and installs the gems
pages:tells the CI what to run and where to put the resulting files. Gitlab pages will automatically see these files and start serving them.
Now commit those changes. You’ll need to make an account on Gitlab and then make a new repository. You can make the repository public or private, this has no effect on the final website. Push your site to Gitlab.
In your Gitlab project, go to Settings > Pages and add a new domain. Gitlab requires SSL for custom domains, and there’s a few ways you can do this.
- If you use Cloudflare, you can generate free origin certificates. Cloudflare will provide you with two keys to go in the two boxes on Gitlab. You’ll need to add Cloudflare’s RSA root cert after your generated cert in the Certificate (PEM) field.
- If you already have a valid certificate for this domain you can use that.
- If not, you can use LetsEncrypt but this method requires you to manually renew every 90 days.
You will be asked to add a TXT record to the domain to verify ownership, and create the correct DNS record pointing to Gitlab pages. You can get the details on the Gitlab documentation site.
- If you’re hosting your site on the root domain (like this one) use the A record and corresponding TXT record.
- If you’re using a subdomain, use a CNAME record and the corresponding TXT record.
If you are using Cloudflare’s flexible SSL, make sure to uncheck the Force domains with SSL certificates to use HTTPS box on the Pages settings, otherwise your website will infinitely redirect.
Updating your site
When you want to update your site, just push to Gitlab. To check the progress of compiling your site, go to CI/CD > Pipelines. For each commit the current progress is shown, click it to see the live command line output.