Trying to get Jekyll running on macOS Catalina but hitting a brick wall and the Jekyll documentation isn’t helping? Yeah, I did too. Thankfully I managed to figure it out, so you don’t have to. The following steps are based loosely on the steps in the official guidance and assume a clean install, but they should work on any Catalina system.

1. Install Xcode via the AppStore

2. Install the Xcode command line tools

Open up a Terminal and type:

% xcode-select --install

3. Agree to the Xcode licence agreement

% sudo xcodebuild -licence

You can also do this through the Xcode GUI. This step isn’t covered in the official Jekyll documentation, but it is super important. If you don’t agree to the licence then tools like make won’t be available, and they’re essential to the next steps. It’s also really easy to miss if you never actually use Xcode or if you’ve just not run it since the last update.

4. Install Ruby

This is the part where you install a compatible version of Ruby, but thankfully Catalina already comes with one supplied so there’s nothing to do here.

5. Install Bundler and Jekyll

% gem install --user-install bundler jekyll

6. Fix your path

Here you just need to check your Ruby version and add it to your path

% ruby -v
ruby 2.6.3p62 (2019-04-16 revision 67580) [universal.x86_64-darwin19]

And then append that to your path, replacing the X.X with the first two digits of your Ruby version.

% echo 'export PATH="$HOME/.gem/ruby/X.X.0/bin:$PATH"' >> ~/.zshrc

then run

% . ~/.zshrc

to activate your changes (without having to close your Terminal window).

You may note this is using ~/.zshrc and not ~/.bash_profile, as per the official documentation, this is because macOS Catalina replaced bash with zsh as the default shell.

7. Done

And there you have it, installing Jekyll on macOS Catalina. It’s not tricky but there are a couple of big gotchas (the licence and zsh) which aren’t mentioned at all in the official documentation.