How to build a Jekyll + GitHub Pages site

April 6, 2022

This site is built using Jekyll that turns the Markdown and HTML templates into a themed static site. To run Jekyll, install the Ruby via the Ruby Version Manager and install the github-pages Gem (a Ruby package) via Bundler. Installing the github-pages Gem will install the Jekyll executable.

Step 1: install Ruby with the Ruby Version Manager (RVM):

There are too many ways to install Ruby. If you (like me) don’t know anything about Ruby then just install Ruby with RVM.

• Following the instructions at https://rvm.io to install RVM. (Follow the Basic Install instructions to install the latest stable version of RVM)
• For Ubuntu users, read this after you read the above: https://github.com/rvm/ubuntu_rvm

Make sure you install the version of ruby (via rvm install) compatible with GitHub Pages. Set the current (and default) ruby installation to the compatible version via rvm alias create default <version>.

Step 2: install dependencies, build and serve the site

Follow the github.com instructions.

tl;dr:

• bundler should be installed as part of ruby 2.x.
• You basically only need the github-pages gem, and can specify the dependency as part of the Gemfile
• bundle install to install dependencies
• bundle exec jekyll serve to build and serve the site locally to localhost:4000

Troubleshooting:

• Add: [[ -s "$HOME/.rvm/scripts/rvm" ]] && source "$HOME/.rvm/scripts/rvm" to your .bashrc or .zshrc etc. if ruby is not found.
• Check github-pages gem compatibility at https://pages.github.com/versions/
  • As of Apr 2022, Jekyll 3.9 requires Ruby 2.7.3, and is not compatible with Ruby 3.x