Running Jekyll on a Mac

At the beginning of the year, I had two new Macs in a row in one month. I changed my company and had to return my previous laptop. Thus, I ordered a replacement one, but due to the current hardware shortage, the shipping took weeks: I had to rent one in the meanwhile.

It means I had to install my Jekyll stack twice in a row. The first time took quite some time; the second one was much faster.

In this post, I'd like to write it down once and for all to help other developers who want to do the same and my future self.

A new Mac OS system comes with an already installed Ruby distribution. Unfortunately, you cannot upgrade it. On my Mac, at the time of this writing, it's 2.6.8p205 (2021-07-07 revision 67951).

The first step is to install a more modern version. For this, we need first to install rbenv:

Use rbenv to pick a Ruby version for your application and guarantee that your development environment matches production. Put rbenv to work with Bundler for painless Ruby upgrades and bulletproof deployments.

-- https://github.com/rbenv/rbenv

Note that the following relies on Homebrew, the command-line package manager for Mac OS. That's the first thing I install when I acquire a new one.

brew install rbenv

Next, we have to initialize our shell. For that, let's update our shell profile:

eval "$(rbenv init - zsh)"

I'm using the default Z-shell. If you're using another shell, locate its profile.

Then, we need to execute the profile in the current Terminal window:

. ~/.zshrc

At this point, we should list all available Ruby distributions:

rbenv install --list

The output should be similar to the following:

2.6.9
2.7.5
3.0.3
3.1.1
jruby-9.3.4.0
mruby-3.0.0
rbx-5.0
truffleruby-22.0.0.2
truffleruby+graalvm-22.0.0.2

Let's install the latest "standard" version:

rbenv install 3.1.1

We can now use this version. Go to your Jekyll folder and type:

rbenv local 3.1.1

I manage the dependencies of my Jekyll blog with Bundler. Bundler is a Gem like all others:

gem install bundler

Dependencies are written in my Gemfile. We can execute bundler to install them:

bundle install

At this stage, a standard Jekyll blog should work. Yet, my blog also uses Asciidoctor, and more importantly, asciidoctor-diagram. I draw my diagrams using the PlantUML syntax. PlantUML requires a JVM and graphviz.

For the JVM, you can either install a dedicated one or install JRuby instead of a simple Ruby distribution. graphviz requires a dedicated executable:

brew install graphviz

Et voilà !

If I had to follow these steps more frequently than this, I'd probably automate it further.

To go further:

• Jekyll
• rbenv
• rbenv cheatsheet
• Bundler

Originally published at A Java Geek on June 5^th, 2022