Set up Ruby, Bundler and a project-level Jekyll on macOS Catalina and up

install_ruby_bundler_project_jekyll.md

Set up Jekyll environment on macOS

Set p Ruby, Bundler and a project-level Jekyll on macOS Catalina and up

This guide is for macOS Catalina and is based on the Jekyll on macOS doc and my experience.

1. Install dev tools

Use the XCode CLI to install dev tools. Recommended so that you can install native extensions when installing gems.

$ xcode-select --install

2. Install Ruby

Your system already has a Ruby installed, but its version and gems are locked in Catalina. So here we install another Ruby using Homebrew.

1. Install Homebrew package manager.
   • See instructions on brew.sh homepage.
2. Use Homebrew to install Ruby - see ruby formula. Note version 3 is not suitable yet for Jekyll.

   $ brew install ruby@2.7

3. Choose a relevant shell config to edit. For Bash, use ~/.bashrc, .profile or .bash_profile in the next steps. For ZSH, use ~/.zshrc or ~/.zshenv.
4. Add the following to your shell config. This will ensure so that your Homebrew install of Ruby will be found before the system Ruby at /usr/bin/ruby.

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

3. Set up system gems

If you want to install in a shared directory (owned by root and shared across users for reading), use this.

$ gem install bundler

$ which -a bundler
/usr/local/opt/ruby/bin/bundler

If you get a prompt to use sudo, then cancel the install command. And rather install in your user's ~/.gem directory instead as below.

1. Add the following to your shell config. This will add something like ~/.gem/ruby/2.7.0/bin to your PATH, so your gems can be run from anywhere.

   GEM_PATH="$(ruby -r rubygems -e 'puts Gem.user_dir')/bin"
   export PATH="$GEM_PATH:$PATH"

2. Open a new terminal to reload your shell configs.
3. Install Bundler in your user's ~/.gem/ directory. Using flag as below to avoid sudo use.

   $ gem install bundler --user-install

   $ which -a bundler
   /Users/mcurrin/.gem/ruby/2.7.0/bin/bundler

4. Install project-scoped gems

1. Add these two gems to your Gemfile.

   gem "jekyll", "~> 3.9"
   gem "kramdown-parser-gfm", "~> 1.1.0"

   • Here the version matches that of the locked versions on GH Pages. If you don't use GH Pages, I recommend a newer version like Jekyll ~> 4.2.
   • For Jekyll 3.9 (and not 3.8 or 4), you need do the Kramdown parser explicitly to avoid errors.
2. Configure Bundler in your project. Make sure you use the --local flag to avoid editing the global Bundler config. See also the Bundle config docs.

   $ cd my-jekyll-project
   $ bundle config set --local path vendor/bundle

   Check the contents of the YAML Bundler config. Once this file exists, you don't have to set it up. But make sure to add it to the ignore file and set it up on each machine.

   $ cat .bundle/config

   ---
   BUNDLE_PATH: "vendor/bundle"

3. Install project gems.

   $ bundle install

   Check installed gems.

   $ ls vendor/bundle/ruby/2.7.0/gems

   addressable-2.7.0           jekyll-feed-0.15.1          minima-2.5.1
   colorator-1.1.0             jekyll-sass-converter-1.5.2 pathutil-0.16.2
   ...
   

5. Run Jekyll in your project

Serve:

$ bundle exec jekyll serve --trace --livereload

Build:

$ bundle exec jekyll build --trace

Tip: If you run into issues installing or running because of libffi or ffi_c missing, you can try these:

brew install libffi

gem install ffi --user-install
# Or
sudo gem install ffi