Skip to main content
This article is a little old. The information herein might not be too accurate.

Using Jekyll plugins on Github Pages

Quite wisely GitHub don’t allow you to use Jekyll plugins when deploying to GitHub Pages, but here I'll show you how you can still utilize their benefits.

We host this blog on Github Pages, and one of the first challenges we came across was that they run Jekyll in --safe mode, which means you’re unable to use plugins. This is essential for Github from a security standpoint, however it can leave you feeling frustrated if you want to extend the functionality of Jekyll.

You need to build your site before deployment

The simple way around this, is to build the site locally and then deploy the contents of your _site folder rather than the entire source of the site. This way Github doesn’t have to build it.

Have Rake do all the work for you

Manually building and deploying can be a laborious process, so we’ve compiled ourselves a simple Rake task which does all the heavy lifting for us.

Octopress has something similar, but if you don’t want the bloat of the entire framework, something like this works very well.

# Rquire jekyll to compile the site.
require "jekyll"

# Github pages publishing.
namespace :blog do
  # Because we are using 3rd party plugins for jekyll to manage the asset pipeline
  # and suchlike we are unable to just branch the code, we have to process the site
  # localy before pushing it to the branch to publish.
  # We built this little rake task to help make that a little bit eaiser.

  # Usaage:
  # bundle exec rake blog:publish
  desc "Publish blog to gh-pages"
  task :publish do
    # Compile the Jekyll site using the config.{
      "source"      => ".",
      "destination" => "_site",
      "config" => "_config.yml"

    # Get the origin to which we are going to push the site.
    origin = `git config --get remote.origin.url`

    # Make a temporary directory for the build before production release.
    # This will be torn down once the task is complete.
    Dir.mktmpdir do |tmp|
      # Copy accross our compiled _site directory.
      cp_r "_site/.", tmp

      # Switch in to the tmp dir.
      Dir.chdir tmp

      # Prepare all the content in the repo for deployment.
      system "git init" # Init the repo.
      system "git add . && git commit -m 'Site updated at #{}'" # Add and commit all the files.

      # Add the origin remote for the parent repo to the tmp folder.
      system "git remote add origin #{origin}"

      # Push the files to the gh-pages branch, forcing an overwrite.
      system "git push origin master:refs/heads/gh-pages --force"

    # Done.

Once added to your Rakefile you can run rake blog:publish and your site will be built locally using any plugins you desire, before being pushed up to the gh-pages branch.

This code is a public Gist, so feel free to contribute any other ideas you have.