Using Jekyll and Github Pages (in 2017)

7 minute read

After reading numerous posts online for using Jekyll and Github Pages together, I faced couple of issues. Lets take a look and see how I addressed some of them.

  • Jekyll 3 now recommends using Gem-based themes. I was not able to find themes other than the ones mentioned here.
  • The ones supported by Github are not exactly blog like.

After spending considerable amount of time looking for a perfect theme (And giving up numerous times). I decided to go with the whiteglass theme.

I cloned the repo and had the blog running locally, it was time to push to my .github.io repo. After, refreshing 3-4 times all I was staring at was a blank white screen. Soon, I got a mail from Github regarding a build warning.

You are attempting to use a Jekyll theme, “jekyll-whiteglass”, which is not supported by GitHub Pages

The Fix

Instead of serving a Jekyll Project directly from the master branch of the github.io repository, we can instead serve the static files generated from the jekyll build command, i.e. the contents of the _site directory. This way, we will remove dependency on Github Pages to build the Jekyll Project, instead it will only serve the static pages.

Since, the master branch will have the “built” website, where should we store the actual Jekyll Project ?

In my case I have stored it in the development branch inside the same repository. I will work on the blog in this branch and will push the built website to the master branch. I have seen some repositories where people have written Travis jobs to do this exact thing. I feel that is an overkill, a slow process and downright exploitation of a free service. Please correct me if I am wrong.

I have written a small shell script which will build the website and push the changes to the master branch. Here it is:

#! /bin/sh

BUILD_DIR="./_site"
TMP_DIR="/tmp/jekyll_build"
CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)

# Delete old build files if any
rm -rf $BUILD_DIR

# Build
bundle exec jekyll build

# If Build succeeds
if [ -d "$BUILD_DIR" ]; then
    echo "JEKYLL: BUILD SUCCESS"
    rm -r $TMP_DIR

    # Move BUILD_DIR to /tmp
    mv $BUILD_DIR $TMP_DIR

    # Change branch to master
    if git checkout master; then
      echo "SUCCESSFULLY SWITCHED TO MASTER"

      # Cleanup
      ls | xargs rm -r

      # Get the build
      mv $TMP_DIR/* .

      # Commit
      git add .
      git commit -m "Deploy $(date)"
      if git push origin master; then
        echo "DEPLOYED SUCCESSFULLY !"
        echo $(basename $(git remote show -n origin | grep Fetch | cut -d: -f2-))
      else
        echo "DEPLOY FAILED !"
      fi
    else
      echo "CANNOT SWITCH BRANCH, ABORTING"
    fi

else
    echo "JEKYLL: BUILD FAILURE"
fi

git checkout $CURRENT_BRANCH

This script lives in the development branch.

After I am done doing my changes to the blog. I push them to the development branch, and then do ./deploy. The script will then make a new commit on master having your latest masterpiece.

Why I don’t like the gem based themes.

I have added the deploy script as a post-commit hook, but unfortunately some changes do not require a commit.

This is because most of the theme related code is now inside the gem’s directory (i.e. not inside my git repo). So, say If I want to change the Google Analytics tracking script, then I’ll need to do the changes in the google_analytics.html file. Since, this file is inside the gem’s directory (in my case at /Users/pulkit/.rvm/gems/ruby-2.2.5/gems/jekyll-whiteglass-1.3.0/_includes/), I cannot make a commit on development to reflect this change.

Gem based themes are good for people who are new to Jekyll and do not wish to modify the themes they use. Since, most of the theme related code is now present in some other directory, users will not be overwhelmed from the directory structure when they do jekyll new. But sooner or later, you’ll need to make some changes to the theme (changing the font size for example). Doing those changes in some other directory and not inside version control is pretty cumbersome and will hurt in the future.

UPDATE: Found out this https://jekyllrb.com/docs/themes/#converting-gem-based-themes-to-regular-themes, this will make your git repo to have all the code ! But then, what is the point of gem-based themes ?

Discussion on HackerNews.

Updated: