GitHub pages doesn't support the direct use of Jekyll plugins. If you do want to use plugins you will need to generate the site locally and push the generated files to the root of the master branch along with a .nojekyll file.

The .nojekyll file tells GitHub that it shouldn't try to run their generation on the files you push.

That way, the github repo will just be a bunch og generated static HTML/CSS with no magic.

I've found a couple of different solutions to keeping both the jekyll source files and the generated site organized, and I chose to look at how Octopress handles the 'deployment' of a site.

I checked out the current master containing all the jekyll files to a new branch called source, went back to master and removed all files from the root folder.

I then wrote this rake task to automate generation and deployment of the jekyll site:

def git_clean?
  git_state = `git status 2> /dev/null | tail -n1`
  clean = (git_state =~ /working directory clean/)
end

task :check_git do
  unless git_clean?
    puts "Dirty repo - commit or discard your changes and run deploy again"
    exit 1
  end
end

desc "Deploy to remote origin"
task :deploy => [:check_git] do
  source_branch = 'source'
  deploy_branch = 'master'
  message = "Site updated at #{Time.now.utc}"

  system "jekyll"
  system "git checkout \"#{deploy_branch}\""
  system "cp -r _site/* . && rm -rf _site/ && touch .nojekyll"

  unless git_clean?
    system "git add . && git commit -m \"#{message}\""
    system "git push origin \"#{deploy_branch}\""
    puts "Pushed to origin with commit message: #{message}"
  else
    puts "No changes to deploy - canceled"
  end

  system "git checkout \"#{source_branch}\""
end

(from Rakefile)

What does the task do?

When I run

$ rake deploy

the following happens:

  1. Ensure there are no uncommitted changes before doing anything
  2. Generate the site with the jekyll command
  3. Switch to master branch
  4. Copy all generated content from _site to root folder
  5. Delete _site folder
  6. Create .nojekyll
  7. Add and commit the new files to master
  8. Push master to GitHub pages
  9. Switch back to source branch

That way I can just work from the source branch, still keep everything in the GitHub pages repo and just use the master branch to let GitHub host my static files.

Since all pages are generated locally, jekyll plugins are only needed locally, which makes the GitHub support for jekyll plugins unnecessary.