Riedl's Blog

Testing Your GitHub Pages Site Locally with Jekyll

Published on 11 Jun 2021
Tags: programming

I use GitHub Pages to host this blog and the most annoying part is constantly pushing changes to the repository and waiting for the site to rebuild to see the changes. This is particularly painful when adding any new styling or JavaScript functionality. I always knew that there was a way to host a Jekyll site locally to do development before pushing the changes to GitHub Pages, but until recently I found it too intimidating to try setting everything up. I wanted to write this post because I finally took the dive and did not find the tutorial on GitHub particularly useful for someone who is completely new to Ruby, Bundler, and Jekyll. The steps I took to get it working are:

1) Install Ruby

I installed the latest version of Ruby using Homebrew. This can be done with the code below. You can skip the first command if you already have Homebrew installed.

$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

$ brew install ruby

After installing Ruby, you will be prompted to add the Ruby install location to your PATH. The installer will provide the correct code to copy and paste.

2) Install Bundler

I installed Bundler using gem as recommended on the Bundler homepage. You can check that gem is already installed and install Bundler as follows:

$ which gem

$ gem install bundler

3) Install Jekyll with GitHub Pages Settings

This is the part of the guide provided by GitHub that lost me and I struggled to figure out what I needed to do. It ended up being quite simple after reading some other blog posts and debugging an error message. All you need to do is navigate to the folder that has all the source files for your Pages site and create a file named Gemfile and add the following lines to the file:

source "https://rubygems.org"
gem "github-pages"
gem "webrick"

This will install Jekyll with the appropriate settings and modules to mimic the setup on GitHub Pages. For some reason, you currently need to manually add the webrick dependency. Once this Gemfile is created you can install everything with:

$ bundle install

4) Launch Jekyll

Once the install is complete, you can launch the Jekyll server with:

$ bundle exec jekyll serve
Configuration file: /path/_config.yml
            Source: .
       Destination: /path/_site
 Incremental build: disabled. Enable with --incremental
                    done in 0.994 seconds.
 Auto-regeneration: enabled for '.'
    Server address:
  Server running... press ctrl-c to stop.

Hopefully this guide will help someone else jumpstart their local blog development for GitHub Pages. Good luck!