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

.bashrc should be replaced with .bash_profile. ~/.bashrc does not get read automatically on macOS. You can test this by adding echo "hello from bashrc" to your ~/.bashrc, and open a new terminal tab. You will not see anything, but if you add echo "hello from bash_profile" to your ~/.bash_profile, you will see the hello statement.

Oh, I didn't realize that.

When I used Bash pre-Catalina, I had this line in my .bash_profile at the time.

. ~/.bashrc

I don't know I made that or it came with it.

I confirmed what you used using what I found is the most reliable for switching shells, with a login flag.

exec -l bash

As discussed in the other GH thread, a .bash_profile is not standard on Debian/Ubuntu. And creating one would prevent any code in .profile from running.

Also I found a table of comparisons.

https://en.wikipedia.org/wiki/Unix_shell#Configuration_files

I've given 3 options for Bash.

I also made some other changes.

Step 4.1: the quotes are not correct. Should be:

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

@sieveLau , fixed, thanks!

@sieveLau , fixed, thanks!

It seems the pair wrapping jekyll is still incorrect.

oops. Thanks, fixed again