Using Sass with Jekyll
September 25, 2014
Updated March 23, 2015: Removed mention of installing Sass gem as Jekyll ships with it’s own converter.
While upgrading my suite of Jekyll themes to utilize the built-in Sass compiler, I found the official docs and example project a bit scattered and incomplete. As such, I decided to put this post together for my own reference down the line. Hopefully it helps you, too.
Table of contents
- Install Sass
- Create a Sass stylesheet
- Link your stylesheet
- Using Sass imports
- Hosting on GitHub Pages
- Example project
For brevity, this post assumes a couple things:
- You have an existing Jekyll project up and running, or know how to start one from scratch.
- Your local Jekyll is using version 2.4.0 or better (check in Terminal with
- You have some knowledge of Sass.
Got all that? Awesome, carry on.
Nothing to install here. Jekyll ships with it’s own Sass converter, so you’re good to go.
Wait, Sass or Scss? As far as I know, Jekyll includes support for both
.scss. If you’re unfamiliar with the differences,
.sass allows you to omit curly braces. I recommend sticking with
.scss—it’s less clever and more approachable.
Create a Sass stylesheet
Create your Sass stylesheet wherever you like. At the top of the file, include a front matter comment, then add your styles after.
For the purpose of this post, I’m putting it within a
css/ directory. Here’s what my typical Jekyll site’s directory looks like:
Assuming that structure, Jekyll will compile your
css/styles.scss file into a CSS file at
Link your stylesheet
Now that we’ve got the CSS being built, the last step is including it in your site’s
<head>. Be aware you may need to tweak the path depending on your setup.
At this point you’re essentially done—this the most basic setup for using Sass with Jekyll. Add you Sass in the source
styles.scss file and compile it simply by starting the Jekyll server.
Using Sass imports
Jekyll includes built-in support for using
@imports to compile multiple source files into one CSS file. Place your partial
.scss files in the default directory,
_sass/ and include them in your main Sass stylesheet like so:
You can also change the default
_sass/ directory to a custom directory in your
Enable minification on your compiled CSS by updating your
_config.yml to include:
Now when Jekyll compiles your Sass, you’ll have no whitespace in your CSS. Be sure to turn this on for production environments if file size is of any concern.
Hosting on GitHub Pages
GitHub Pages has been built with Jekyll in mind—just push your Jekyll site to a branch named
gh-pages to get started. It includes support for compiling Sass (and CoffeeScript!) when you push a commit up.
Curious about what dependencies and versions are on GitHub Pages? Check the versions page.
I’ve turned all this into a super basic example Jekyll project and open sourced it on GitHub. It’s licensed MIT and includes everything mentioned above for setting up Sass with Jekyll.