The agony of setting up Jekyll on macOS Catalina

A summary of hours of painful, albeit somewhat informative, experimentation.

The first thing to note is that macOS Catalina ships with Ruby version 2.6.3 as the default. Moreover, the default directory for installing Gems is not writable without “sudo” access. These are big changes, which led to issues in my Jekyll set-up.

SIDE NOTE: This post is only about Jekyll. However, the popular package manager for macOS, Homebrew, is also written in Ruby. So, even those who don’t use Ruby extensively will run into a few problems. This useful post discusses some of the issues, and ways to overcome them.

The official documentation has the necessary steps to install Jekyll, but skips over any potential issues. The Jekyll Talk forum has many questions, and there are many GitHub issues that link to the errors that crop up. The steps in this article are a summary of what worked for me.

Installing a new version of Ruby

Since messing up the system Ruby version might lead to lots of issues, to do any kind of Ruby development, it’s better to get a separate version of Ruby installed. Homebrew can be used to install the latest version of Ruby (version 2.7.1 at the time of this post). If one needs to maintain and use many versions of Ruby (particularly for developing Rails applications), using rbenv or RVM may be better alternatives. If the first option suits you (like it did for me), I recommend following the instructions in this link to install a separate Ruby version and configure the necessary environment variables. For me, the steps were as follows:

brew install ruby

This installs a keg-only version of Ruby. So, to make this version the default, the “$PATH” variable can be changed by adding the following line to “~/.bash_profile”:

export PATH="/usr/local/opt/ruby/bin:$PATH"

Checking the Ruby paths

The position where these new paths are added in the “$PATH variable” matters. The system Ruby executables are stored in “/usr/bin”. This can be tested using the “which” command:

which ruby
# ==> /usr/bin/ruby
which gem
# ==> /usr/bin/gem

So, the new paths must be present before “/usr/bin” in the “$PATH” variable. Checking the paths after changing the environment variable yields:

which ruby
# ==> /usr/local/opt/ruby/bin/ruby
which gem
# ==> /usr/local/opt/ruby/bin/gem

Installing Gems (eg: Bundler)

The important thing to remember is that all Gems must be installed for the user (not globally). This is done by passing the following flag while installing Gems:

gem install --user-install <name-of-the-gem>

To run the executables that are installed using Gems, the “$PATH” variable must be alterred by adding the following line to “~/.bash_profile”:

# change X.X.0 to reflect the Ruby version 
# eg: 2.7.0 (for version 2.7.1), 2.6.0 (for version 2.6.6)
# the last number must always be 0
export PATH="$HOME/.gem/ruby/X.X.0/bin:$PATH"

Installing Bundler

To install Jekyll, we need two gems: “bundler” and “jekyll”. We can start with installing “bundler” using the command:

gem install --user-install bundler

Modifying the “$PATH” to include the local gem path should ensure that the local version of bundler is used and not the default version that ships with Ruby. Checking the path to bundler on my computer yields:

which bundle
# ==> /Users/mythreyi/.gem/ruby/2.7.0/bin/bundle
# This should not be "/usr/local/opt/ruby/bin/bundle"

Installing Jekyll

It is safe to attempt installing the “jekyll” gem following the steps similar to “bundler” above. The “jekyll” gem has 26 other gem dependencies. Attempting to install “jekyll” will therefore install 27 gems in all.

gem install --user-install jekyll

It’s possible that you might run into issues with compiling some of these gems. I ran into issues with a gem called “ffi” when the gem installer was trying to build native extensions.

Fixing the “ffi” gem error

For me, the error was the flags that were passed to “make” while building the Gem “ffi”. I found this GitHub issue thread to work for me. First, install “libffi” using Homebrew:

brew install libffi

This installs a keg-only version of the “ffi” library. The messages that brew outputs after installing are important. In particular, there is a note regarding updating the “PKG_CONFIG_PATH” variable. This is achieved using the “export” command. Since creating a new Jekyll site runs “bundle install” it is best to add this line to “~/.bash_profile”:

export PKG_CONFIG_PATH="/usr/local/opt/libffi/lib/pkgconfig"

The rest of the install should proceed smoothly after this fix.

Testing Jekyll

Navigate to a directory of choice and run:

jekyll new <name-of-the-site>

This command will create a new directory and install the necessary gems for the site using “bundle install”. The process takes a few minutes depending on the internet speed. After the process is done, start the Jekyll server:

bundle exec jekyll serve

If you’re lucky, the site should be available at “localhost:4000”. I wasn’t always lucky. This worked the first time, but later when I tried it in another directory, I had an issue with the “http_parser.rb” Gem. This seems to be an open issue at the time of writing, but this suggestion of navigating to a directory without a space in the name works for me.

Closing Thoughts

As someone who tinkers a lot with interesting tools in my free time, I often don’t have a lot of time to chase the rabbit holes I want. This is why I put off updating my OS for as long as I could since I had a system which just worked. In fact, I did something that isn’t even remotely advisable: it was June 2020 and I was still running macOS Sierra (yes, Sierra)! When Apple, and more importantly, Homebrew stopped supporting Sierra, I decided to finally jump in and update everything when I had the time.

I have experimented with Jekyll since 2018. I use it for my blogging projects and even my personal website. At the time of writing, I have many old Jekyll projects that now need to be reset to match the current set-up. I can’t even update my website locally if I want to! All this set-up is going to take a while, but I am glad that I finally know how to make them work.

Maybe I should switch to Hugo? :)