Integrate Jekyll With Slim, Zurb Foundation, Compass And An Asset Pipeline

.home h1 Blog Posts ul.posts | {% for post in site.posts %} li span | {{ | datetostring }} » a href="{ post.url }}" | {{ post.title }} | {% endfor %} {% endraw %} ```

Trying to preview the site at this point will result in an error. Good, that's what we want! Now, let's install the Slim templating. All we will need to do is to create a simple plugin that loads the jekyll-slim Gem. Start by creating the file:

% mkdir src/_plugins
% touch src/_plugins/bundler.rb

And add the following content to the bundler.rb file:

require 'rubygems'
require 'bundler/setup'

If you don't have any slim templating errors, running the site locally (remember: bundle exec jekyll server) should result in a working preview.

Awesome! Slim templates are installed.

5. Setup the Asset Pipeline

So far, our blog does not look very fresh, so let's add some styling to it. Linking a simple CSS file would be ok, but not ideal. Integrating it with an asset pipeline allows us a few advantages:

  • Pre processing - We can write styles more quickly with something like SCSS and the asset pipeline will compile it to CSS.
  • Compression - The asset pipeline will compress all of our styles (or javascript) into one file and minify it, even gzip it, to improve our page performance.
  • Template integration - We can universally and easily integrate the styles into our templates.

All we are going to do in this step, is change the background of our header and footer, and adjust the font to look a little better. All the assets will be stored in an _assets folder, so we will start by creating a simple site stylesheet, and removing the default styles:

% mkdir -p src/_assets/css
% touch src/_assets/css/app.scss
% rm -rf src/css

Add this content to the app.scss file:

body {
    font-family: sans-serif;
.header, .footer {
    background-color: #eeeeee;
    p {
        font-weight: 100;

Next, add the following block to your _config.yml file to prepare the configuration for the asset pipeline:

  bundle: true
  compress: true
  output_path: assets
  display_path: nil
  gzip: false

This tells the asset pipeline to bundle all the various CSS files together into one, compress them, minify them, and output them to an assets path in the built site. Here we won't gzip the assets.

Before we tie everything together, let's integrate the compiled stylesheet into our template. To do this, add the following code into the head block of your default.slim file:

{% raw %}
    | { % css_asset_tag global_css %}
      - /_assets/css/app.scss
    | { % endcss_asset_tag %}
{% endraw %}

This will load the single file we have and consolidate it into a cache-busting file. You could add any number of CSS files here, as we will see later.

To finish the installation of the pipeline, we will create another small plugin. The plugin will set up the SCSS compiling and also specify how the file will be compressed; in this case with the yui/compressor Gem. Create the file:

% touch src/_plugins/pipeline.rb

And add the following content:

require 'jekyll_asset_pipeline'

module JekyllAssetPipeline

  # process SCSS files
  class SassConverter < JekyllAssetPipeline::Converter

    Compass.configuration.sass_dir = 'src/_assets/css'

    Compass.sass_engine_options[:load_paths].each do |path|
      Sass.load_paths << path

    def self.filetype

    def convert, syntax: :scss).render

  class CssCompressor < JekyllAssetPipeline::Compressor
    require 'yui/compressor'

    def self.filetype

    def compress


Start (or restart) your local server and you should see some output along these lines:

Generating... Asset Pipeline: Processing 'css_asset_tag' manifest 'global_css'
Asset Pipeline: Saved 'global_css-b1d5a3073ad08d4d302e82b7e3900a46.css' to '/path/to/my-blog/build/assets'

And when you preview it in the browser, it should look marginally better.

6. Adding Zurb Foundation and Compass Support

Our site may look a little better, but it's nothing to write your mom about. To take it to the next level, we will integrate the sweet Zurb Foundation CSS framework and support for the great Compass framework. This is a rather straight forward modification to our existing plugin and templates.

Add the following to the top of your pipeline.rb file:

require 'compass'
require 'zurb-foundation'

And the following at the beginning of the definition for the SassConverter in the same file.

    Compass.sass_engine_options[:load_paths].each do |path|
      Sass.load_paths << path

These changes will include the Zurb and Compass Gems and add the Compass path to the load paths where the compiler will look for included files. Now, you can import any of the interesting Compass CSS3 mixins and what not, as well as the Foundation framework.

Simply add the following line to the top of your app.scss file to import all the Zurb Foundation goodness:

@import "foundation";

Finally let's update our default.slim layout to make our site look a little more reasonable. It's still not going to win any awards, but feel free to play around with the styles all you like in your version. Update the default.slim file with this content:

{% raw %}
doctype html
    | {% css_asset_tag global_css %}
      - /_assets/css/app.scss
    | {% endcss_asset_tag %}
      | {{ page.title }}
            a href="/"
              | {{ }}
          a.button.small href="/" Home
      | {{ content }}
            p Your Name
{% endraw %}

Again, restart your server and you should have a basic site.

One thing I would recommend is that you also import the standard _settings.scss file from Zurb Foundation. A version of the settings file can be found in the Foundation docs. This will let you quickly modify the global variables that drive the framework and very quickly add a theme to your blog.

7. Integrate Guard for Quick Development

At this point, you may have found that you have been restarting the Jekyll server quite a bit to update to see your changes. Alternatively, there is the bundle exec jekyll server -w command which will watch for changes to the source files and then regenerate your site. This is helpful, but I think we can do better.

By installing the guard-jekyll-plus Gem along with livereload we can make the development process seamless. Make a change in a source file, and the site will be regenerated and your browser refreshed!

Begin by creating a Guardfile in the root of your project:

% touch Guardfile

And fill it with these contents:

guard 'jekyll-plus', extensions: %w[slim yml scss js md html xml txt rb], serve: true do
  watch /.*/
  ignore /^build/

guard 'livereload' do
  watch /^src/

Next, ensure you have the Chrome Livereload extension installed. (I believe there is also one for Firefox)..

Now, rather than starting up the server the old fashioned way, let's do it the new fangled way:

bundle exec guard

You should see start up messages and that a browser is connected. Go ahead and change something in your site layout or style sheets, and watch the browser reload automatically!

It's worth mentioning that the asset pipeline, especially with the rather large Foundation framework, can slow down this refresh process. Some ways to speed it up include:

  • Only import the bare minimum from your supporting frameworks. Zurb Foundation lets you import sections relevant to your goals; this cuts down on the payload as well as speeds up the asset processing.
  • Run different development settings. The Jekyll Guard plugin lets you load multiple configuration files, where the later overrides the former. I use this to turn off most of the asset processing, and other time intensive things, during normal development.

8. Deploying to Heroku Cleanly

Alright! We have the beginnings of a rather nice blog. Quick templating with Slim, rapid styling with Compass and SCSS, a good looking base style with Zurb Foundation, and an asset pipeline to package it all together. All that's left is to deploy and show it off!

Heroku let's us deploy our Jekyll blog very easily. However, there are few adjustments to make first that will improve the process:

  1. Don't commit your builds! While it is quite simple and commonplace to just "commit everything" and push master to Heroku, it's messy. I don't want my code base cluttered up with various states of a generated site. Here, we will push only the source to Heroku and let it build our finished product.
  2. Improved middleware. By adding some Rack extensions, we can fix many of the issues page analyzers complain about, speed up the site, and make search engines happy.

To begin, we will create the necessary files:

% touch
% touch Procfile
% touch Rakefile
% echo '<h1>404: Page Not Found!</h1>' > src/404.html
% touch src/favicon.ico

(I've found there to be errors in the deploy process when Heroku looks for the favicon.ico file. Which is why we are creating one).

I use Rake for all sorts of development-related tasks, and you should too; but for now, all we will do is add the following to the Rakefile:

namespace :assets do
  desc 'Build Site'
  task :precompile do
    sh 'bundle exec jekyll build'

An interesting thing about Heroku, is that by default, it will attempt to run the assets:precompile Rake task in its standard Ruby build process. All we are doing here is asking that when it runs this task, it should build our Jekyll site. There's no need to install any custom build process.

The Procfile is rather straight forward and configures the Puma server for our site:

web:     bundle exec puma -p $PORT

And lastly, we will build out the file with the necessary middleware inline; I've added comments about the role of each part:

# Set the encoding
Encoding.default_internal = Encoding::UTF_8

require 'bundler/setup'
require 'rack/contrib/try_static'
require 'rack/contrib/not_found'
require 'rack/rewrite'

# Set up asset compression
use Rack::Deflater


# Set up redirects
use Rack::Rewrite do
  # There should only be one canonical permalink, and it should not end with index.html
  r301 /(.*)\/index\.html$/i, '$1'

  # Redirect any calls to the the canonical domain, unless they are to the canonical domain
  # This prevents accessing the app from the heroku url or your domain
  r301 /.*/, '$&', if: proc { |rack_env| rack_env['SERVER_NAME'] != '' }

# Ensure the site is served from the correct location and the headers are appropriate
use Rack::TryStatic,
  urls: %w[/],
  root: 'build',
  try: ['index.html', '/index.html'],
  header_rules: [
    ['atom.xml', { 'Content-Type' => 'application/atom+xml' }],
    [['xml'], { 'Content-Type' => 'application/xml' }],
    [['html'],  { 'Content-Type' => 'text/html; charset=utf-8' }],
    [['css'],   { 'Content-Type' => 'text/css' }],
    [['js'],    { 'Content-Type' => 'text/javascript' }],
    [['png'],   { 'Content-Type' => 'image/png' }],
    ['/assets', { 'Cache-Control' => 'public, max-age=31536000' }],

# 404s should be sent to that simple page we created above

Now, at last, we can deploy our site by committing, creating a Heroku site and pushing master. (Unless you have already associated your own domain with this build, you will want to remove the rewrite stuff from the file). Assuming you have already installed the local Heroku tools, just use these commands:

% git add .
% git commit -m 'Built out a sweet site.'
% heroku create
% git remote add heroku
% git push heroku master

Now, watch the magic happen. You'll notice after the Gems are installed the message Running: rake assets:precompile, here we see the standard build process building your site. Then, you should also notice the asset pipeline doing its work. And eventually, the deploy process will be complete and you can see your new, fresh blog live and in production.

When I ran YSlow, the site scored a perfect 100.

Although, obviously, there is not much here to slow the site down, at least we have a clean and fast foundation upon which to quickly iterate a Jekyll blog.

Please let me know if you run into any problems while working through this tutorial. The full source of Never Stop Building is available on Github for your reference. Best of luck!

If you enjoyed reading this or learned something, please consider sharing via , , or . Thanks!