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.

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.

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

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:

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

The output should be similar to the following:

Let’s install the latest “standard” version:

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

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

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

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:

Et voilà !

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

To go further:

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



Dev Advocate for Apache APISIX. Former developer and architect. Still teaching, learning and blogging.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Nicolas Fränkel

Dev Advocate for Apache APISIX. Former developer and architect. Still teaching, learning and blogging.