Using Jekyll plugins with Github Pages

Jan 2015

Jekyll is awesome. Free hosting with Github Pages is also awesome. The only slight downside is that Jekyll sites on Github Pages are generated with a –safe flag to prevent arbitrary Ruby code being executed. This means you are very limited to the amount of plugins you can use which sucks.

There are of course a few nifty workarounds which allow you to use plugins with Jekyll, most of them running with the idea that you have your development code on a separate branch, and then use some kind of automation to push the _site directory where the static files live to the gh-pages branch where the site is served from.

I’ve looked lots for a convincing workaround to this issue and the one that proved to be most useful for me personally has been a grunt plugin.

I’m a huge fan of GulpJS and Grunt, both Javascript task runners. Thankfully there is a brilliant open-source grunt plugin that allows you to quickly push the built static site files to the gh-pages branch to be served. Check out the repo for detailed instructions here

A quick example grunt task to deploy the _site directory to gh-pages:

module.exports = function(grunt) {

  grunt.loadNpmTasks('grunt-build-control');
  
  grunt.initConfig({

    buildcontrol: {
      options: {
        dir: '_site',
        commit: true,
        push: true,
        message: 'Built %sourceName% from commit %sourceCommit% on branch %sourceBranch%'
      },
      pages: {
        options: {
          remote: 'git@github.com:James-Oldfield/jamesoldfield2015.git',
          branch: 'gh-pages'
        }
      }
    }
  });

grunt.registerTask('default', [
    'buildcontrol:pages'
  ]);

};

So as and when you need to push changes up to the deployment branch, simply run the following from the development branch:

$ jekyll build
$ git checkout dev
$ git add -A
$ git commit -m "made changes"
$ git push origin dev
$ grunt buildcontrol:pages

This will push the _site directory to gh-pages branch at github automatically, allowing you to build with whatever plugin or ruby code you like locally, and deploy the static sites’ files to Github like that.