Configuring Jekyll for GitHub Pages took longer than expected. Instead of linking to Jekyll’s quick start guide, Pages should have pointed me to its set-up instructions for local Jekyll installations.

This was my process:

  1. I followed the steps found on Jekyll’s guide, which led me to install Jekyll v3.3.0. I later learned that Pages only supports v3.2.1.
  2. Jekyll v3.3.0 works locally, but once I committed my changes, GitHub was either sending me “failed build” errors, or my pages would not display properly.
  3. Once I learned about Pages’ dependencies, I started thoroughly reading the docs. What finally made my local and online pages look the same was the github-pages gem:
gem "github-pages", '>=98', group: :jekyll_plugins
# Note 1: 98 is the latest version
# Note 2: If I ommit >=98, then the version I get from rubygems.org is 35.

I still have issues. Whenever I run jekyll build, I get warnings about GitHub apis. Also, my local build’s links have a prefix of github.com/pages/. These issues go away when I remove the github-pages gem and add the jekyll gem; see Step 3 of the set-up page for an explanation of what Jekyll v3.2 does to your Gemfile:

Note: As of Jekyll 3.2, the default Jekyll site contains a Gemfile that locks Jekyll to the Gem version you build it with. To instead lock it to the version used by GitHub Pages, you’ll uncomment the gem “github-pages”, group: :jekyll_plugins line in the steps below.

Despite the issues I encountered, I am grateful for Pages’ thorough documentation and for a chance to use Jekyll as a website and blogging tool.