Jekyll Asset Pipeline with Stylus and Revisions

We use Jekyll for this blog and for the other pages on floored.com and host them on Github Pages. We find it simpler and faster than app-y alternatives.

One thing we did miss though was having an asset pipeline for our CSS and JS.

Jekyll has a plugin system for adding functionality like this. (Unfortunately, adding a plugin adds an extra step to publishing since Github will not use custom plugins when they generate a site.) We looked at a lot of asset management solutions but ended up with our own plugin, heavily based on jekyll-asset-pipeline.

Asset Bundle Features

  • We can develop locally with Stylus files and multiple JS files (no Coffeescript).
  • The plugin generates CSS files from the .styl files and reads a .yml file to add the <link> and <script> tags to the html
  • When publishing, the plugin concats all the files together, compresses them with Stylus or Uglifier, adds a md5 fingerprint to the filename, and inserts the <script> and <link> tags to the html.

Setup

  1. In our Gemfile: {% highlight ruby %} gem 'jekyllassetbundle', :github => 'floored/jekyllassetbundle' {% endhighlight %}

  2. In _plugins/assets.rb: {% highlight ruby %} Jekyll::ENV = (ENV['JEKYLL_ENV'] || 'development') require 'jekyllassetbundle' {% endhighlight %}

  3. In Rakefile: {% highlight ruby %} task :build do ENV['JEKYLL_ENV'] = 'production'
    sh "jekyll build" end {% endhighlight %}

How we use it

All our CSS and JS go into an _assets folder:

_assets/
  css/
    application.styl
    nib/
      clearfix.styl
      config.styl
      index.styl
    normalize.styl          
  js/
    application.js
    app.yml
    carousel.js  
    

We use these liquid tags in the template: {% raw %} {% css application %} {% js app %} {% endraw %}

When jekyll sees those tags, it generates the css and js files into _site/assets. In development, the generated html looks like:

{% highlight html %}

{% endhighlight %} In production, the generated html looks like:

{% highlight html %}

{% endhighlight %}