Using Jekyll gem-based themes on Github Pages

TL;DR. GitHub Pages doesn’t currently support 3rd party theme gems. You can workaround this, by building Jekyll in your local machine or in a CI service like Travis-CI and push to Github the generated files inside _site.

WARNING: This is not supposed to be a step by step tutorial, but my experience and some hints on how you can archive the same thing.

UPDATE: Since 29 of November 2017, GitHub Pages announced support for Jekyll Gem-based themes that are hosted on GitHub. This means that now you have two options to use Jekyll Gem-based themes on GitHub Pages:

• GitHub Pages new support for Gem-based themes Click here for more details.
• Building Jekyll in your local machine or in a CI service as discussed on this blog post.

The initial idea

When I was setting up this blog, I wanted to use Github Pages and Jekyll.

I follow some tutorials, forked a few different themes, but it felt a hack to fork a repository, keep it update with original, making local changes which could result in future conflicts, bah That’s something that I didn’t want to do for a simple blog… I want to apply the KISS principle.

Then I find out that since version 3.2, Jekyll start supporting Gem-based themes, which seems what I was looking for, but after a quick search I find out this:

Note: Not all Jekyll themes are supported. For a list of Jekyll themes that are supported by GitHub Pages, see https://pages.github.com/themes.

Adding a Jekyll theme to your GitHub Pages site

Github Pages only support a small number of themes, which made me return to the original plan of forking a repository.

A better way

After a while, when I was trying a new theme I found this github issue.

Question: Use with GH pages without requiring fork?

Answer: … The problem is GitHub Pages doesn’t currently support 3rd party theme gems. Similar to how they don’t allow Jekyll plugins (except for a few that have been whitelisted). So instead of pushing commits to GH and having it build your site, you need to build it locally and push the contents of your _site folder. … A lot of people use CI services like Travis to build their site and deploy to GH.

Question: Use with GH pages without requiring fork? · Issue #662 · mmistakes/minimal-mistakes

This was exactly what I was trying to archive! Basically if I perform the Jekyll build outside of github, like on my local machine or Travis-CI, I could still use Jekyll Gem-based themes, and push to github only the generated file inside _site.

I already tried the Jasper theme with Travis-CI so maybe that wouldn’t be that hard.

I followed this guide especially the sections Ruby Gem Method and Setup Your Site.

The most important files to get started are:

• _config.yml for blog configuration (modified from https://github.com/mmistakes/minimal-mistakes)
• .travis.yml for Travis-CI configuration (modified from https://github.com/biomadeira/jasper/blob/master/.travis.yml)
• Rakefile which is invoked by Travis-CI to build Jekyll and push the _site directory to master branch (modified from https://github.com/biomadeira/jasper/blob/master/Rakefile)
• gemfile where I put my dependencies like Github Pages or Jekyll, Gem-based Theme, and some build dependencies

And after some tweaking and failed build’s, I got it working!

Conclusion

In general I’m satisfied with the setup, Travis-CI does all the heavy lifting for me, it builds the site in every commit, although I would like that the build times were faster, currently they are around two and half minutes.

If you have any suggestion to improve, or any issue trying to reproduce what I describe, please let me know.