@mdo

Using Sass with Jekyll

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

Assumptions

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 jekyll --version).
  • You have some knowledge of Sass.

Got all that? Awesome, carry on.

Install Sass

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 .sass and .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.

---
# Front matter comment to ensure Jekyll properly reads file.
---

// Add your styles here

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:

jekyll-project/
├── _includes/
├── _layouts/
├── _posts/
└── css/
│   └── styles.scss
├── _config.yml
└── index.html

Assuming that structure, Jekyll will compile your css/styles.scss file into a CSS file at _site/css/styles.css.

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.

<link rel="stylesheet" href="/css/styles.css">

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:

---
# Front matter comment to ensure Jekyll properly reads file.
---

// Imports
@import "base";
@import "type";
@import "layout";

You can also change the default _sass/ directory to a custom directory in your _config.yml:

sass:
  sass_dir: _lib

Minification

Enable minification on your compiled CSS by updating your _config.yml to include:

sass:
  style: compressed

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.

Example project

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.

Enjoy!