I host a blog on github pages that is generated using jekyll. Every time I get a new Mac, I need to set up the backend for developing the blog. This setup process always takes way longer than I'd like, so it's documented here for convenience.

System setup: install homebrew & ruby

Jekyll is a ruby package, and thus requires us to have ruby installed on our machine. Note that Macs come with a system installation of ruby, e.g. if you run

which ruby
# /usr/bin/ruby

ruby -v
# ruby 2.6.10p210 (2022-04-12 revision 67958) [universal.arm64e-darwin22]

you see that ruby is already packaged with your Mac. However, this is't the ruby you want to use because a) it's likely an outdated version (e.g. 2.6.*, and we want to be using v 3.0.*), and b) you generally don't want be fiddling with the system setup packaged by Apple. Instead, we'll install our own version of ruby using the Mac package manager homebrew.

Install homebrew

If, for whatever reason, you do not have homebrew installed, go to https://brew.sh , and copy the install Install Homebrew command, then paste and run in the terminal, e.g.

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

⚠️ Note this command should install XCode developer tools as well; these are required, and you should accept their installation if prompted.

Finish homebrew install

Make sure to run the Next steps commands that are displayed in the terminal. These will update your shell profile to use brew whenever a new shell is created. Just copy/paste the commands into the terminal to run them. Note that {USERNAME} in the command below should be your own username, and {SHELL_PROFILE} will be your shell configuration file (e.g. .zshrc or .bash_profile).

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> /Users/{USERNAME}/{SHELL_PROFILE}
eval "$(/opt/homebrew/bin/brew shellenv)"

Install ruby via brew

First create an environment variable pointing to the system SDK root. This will ensure that any jekyll components that require ruby have access to them.

export SDKROOT=$(xcrun --show-sdk-path)

Modern jekyll (>4.0) requires ruby 3.0, so we'll install ruby 3.0 using brew.

brew install [email protected]

Finish the ruby install

In order to make the homebrew version of ruby the default, you'll need to prepend it to your search path. To do so, copy/paste the command printed to the terminal: If you need to have [email protected] first in your PATH, run:, where {SHELL_PROFILE} will be your shell configuration file (e.g. .zshrc or .bash_profile).

echo 'export PATH="/opt/homebrew/opt/[email protected]/bin:$PATH"' >> ~/{SHELL_PROFILE}

Now reload the shell so that the default ruby is available

# Reload the shell with updated PATH
source ~/{SHELL_PROFILE}

# Check ruby source, should be homebrew
which ruby
# /opt/homebrew/opt/[email protected]/bin/ruby

# Check ruby version
ruby -v
# ruby 3.0.6p216 (2023-03-30 revision 23a532679b) [arm64-darwin22]

In this example, we see that we're using ruby version 3.0.6, excellent 🤘

Install bundler & jekyll

To manage the ruby packages (aka gems) required for jekyll, we'll need bundler, so we need to install that. While we're at it, we may as well install jekyll too. Note: we'll perform this install for the current user, rather than globally.

# Optional gems update
gem update

# Install bundler and jekyll
gem install --user-install bundler jekyll

You may get the following warning after the install:

WARNING:  You don't have /Users/{USERNAME}/.gem/ruby/3.0.0/bin in your PATH,
     gem executables will not run.

That's fine and expected, you can remedy this by prepending the gem binaries to your search path:

# Add gem executables to search path
echo 'export PATH="/Users/{USERNAME}/.gem/ruby/3.0.0/bin:$PATH"' >> ~/{SHELL_PROFILE}

You can verify that all your paths are set up correctly by checking your ruby/gem environment:

gem env

The GEM PATHS section of the output should look like:

 - GEM PATHS:
     - /opt/homebrew/lib/ruby/gems/3.0.0
     - /Users/{USERNAME}/.gem/ruby/3.0.0
     - /opt/homebrew/Cellar/[email protected]/3.0.6_1/lib/ruby/gems/3.0.0

where all paths are now linked to ruby 3.0.

Initialize jekyll site

If you already have a site, copy it over or clone it from github, e.g.

git clone [email protected]:{GITHUB_USERNAME}/{BLOG_REPO_NAME}.git
cd {BLOG_REPO_NAME}

Otherwise, you'll need to initialize the blog using the standard jekyll workflow:

# Create space for site
mkdir {/PATH/TO/NEW_SITE}
cd {/PATH/TO/NEW_SITE}

# Add Gemfile and Gemfile.lock to site
bundle add jekyll --version "~>4.0"

# Initialize new site files in current directory, ignoring the presence of current Gem* files
bundle exec jeckyll new --force .

Install webrick

jekyll has a dependency on webrick (which used to be part of the standard library, but is no longer in version 3.0), so we'll need to install that dependency as well.

# Add webrick to gems
bundle add webrick

# Install webrick
bundle install

Start the development server

Now you should be able to start the server in development mode via

bundle exec jekyll serve --livereload

Happy developing!