Setting up a Mac to run Ruby and Jekyll

I had some challenges trying to run Ruby and Jekyll on my Mac. Don't ask why. Probably not enough coffee or the fact that I was new to using Macs, having run Bill Gates OS for many years. Anyway, I finally got it running and basically this is how I did it.

Which Ruby version does you Mac currently have? You need Ruby version 2.5.0 or higher

According to the Jekyll documentation, you need at least Ruby version 2.5.0 or higher. You can check which version is installed on your MAC using the following command.

1
2
3
4
$ ruby -v
#
# On my MAC it showed the following version:
# ruby 2.6.5p114 (2019-10-01 revision 67812) [x86_64-darwin17]

Of course, if you do not have Ruby installed on your MAC, then you need to install it. The website Installing Ruby suggests using the Homebrew command (Homebrew is installed by default on macOS).

1
2
3
$ brew install ruby
#
# This installs the latest version of Ruby.

If you received an error after running this command, you may need to upgrade Ruby using the following:

1
2
3
$ brew upgrade ruby
#
# This command upgrades Ruby to the latest version.

This may take a few minutes. You may need to add this new version to your PATH.


See Also: You can follow the steps here to upgrade a Mac OSx to the latest version of Ruby.


You should restart your terminal to have the terminal recognize the new Ruby version. Then re-run the Ruby version command.

1
2
3
4
$ ruby -v
#
# On my MAC it now showed the following version:
# ruby 2.7.2p137 (2020-10-01 revision 5445e04352) [x86_64-darwin17]

Which Gem is your Mac running?

Jekyll requires the use of RubyGems to run packages. Check which version of RubyGems is on your Mac using the following command.

1
2
3
4
$ gem -v
#
# On my MAC is show the following version:
$ 3.1.4

If you need to install RubyGems. Try running the following first to see where, if at all, RubyGems is running on your Mac.

1
2
3
4
$ which gem
#
# On my MAC is show the following:
$ /usr/local/opt/ruby/bin/gem

If you need to install/update RubyGems, you can try the following

1
2
3
4
$ gem update --system
#
# On my MAC is show the following:
$ Latest version already installed. Done.

You need to Install Bundler

Now, you need to install Bundler which “provides a consistent environment for Ruby projects by tracking and installing the exact gems and versions that are needed.”

First, let’s see if bundler is already installed on your Mac.

1
2
3
4
$ bundler -v
#
# On my MAC is show the following:
$ Bundler version 2.0.2

If you need to install Bundler, simply run the following command.

Note that you need to run this command in the Jekyll project directory.

1
2
3
4
5
6
# cd to the Jekyll project directory
$ cd <jekyll project directory>
# then run the following command to install bundler
$ bundle install
#
# All the required files will be installed in the project directory and a Gemfile will be created.

You can then ensure the version of Bundler is the latest using the following command.

1
2
3
4
$ bundle update --bundler
#
# You should see a list of updated Gems installed.
$ bundle updated!

Now install Jekyll

With Ruby and Bundler installed, you are ready to install Jekyll.

1
2
3
$ gem install --user-install bundler jekyll
#
# This installs Jekyll. It should be the latest, but we will see.

Now check the version of ruby again just for fun.

1
2
3
4
$ ruby -v
#
# This returns the following:
ruby 2.7.2p137 (2020-10-01 revision 5445e04352) [x86_64-darwin17]

We now need to set the path for Ruby. In the following command replace X.X with the first two digits of your Ruby version, which in my case is 2.7

1
2
3
4
5
$ echo 'export PATH="$HOME/.gem/ruby/X.X.0/bin:$PATH"' >> ~/.bash_profile
#
# where X.X is the Ruby version you found by running ruby -v above
#
# echo 'export PATH="$HOME/.gem/ruby/2.7.0/bin:$PATH"' >> ~/.bash_profile

Now let’s look at the gem environment to make sure everything is ok.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
$ gem environment
#
# This results in the following output.
RubyGems Environment:
  - RUBYGEMS VERSION: 3.1.4
  - RUBY VERSION: 2.7.2 (2020-10-01 patchlevel 137) [x86_64-darwin17]
  - INSTALLATION DIRECTORY: /Users/GJL/.rvm/gems/ruby-2.6.5
  - USER INSTALLATION DIRECTORY: /Users/GJL/.gem/ruby/2.7.0
  - RUBY EXECUTABLE: /usr/local/opt/ruby/bin/ruby
  - GIT EXECUTABLE: /usr/bin/git
  - EXECUTABLE DIRECTORY: /usr/GJL/.gem/ruby/2.7.0/bin
  - SPEC CACHE DIRECTORY: /Users/GJL/.gem/specs
  - SYSTEM CONFIGURATION DIRECTORY: /usr/local/Cellar/ruby/2.7.2/etc
  - RUBYGEMS PLATFORMS:
    - ruby
    - x86_64-darwin-17
  - GEM PATHS:
     - /usr/GJL/.gem/ruby/2.7.0
     - /Users/GJL/.rvm/gems/ruby-2.6.5
     - /Users/GJL/.rvm/rubies/ruby-2.6.5/lib/ruby/gems/2.6.0
  - GEM CONFIGURATION:
     - :update_sources => true
     - :verbose => true
     - :backtrace => false
     - :bulk_threshold => 1000
  - REMOTE SOURCES:
     - https://rubygems.org/
  - SHELL PATH:
     - /usr/local/opt/ruby/bin
     - /usr/local/opt/ruby/bin
     - /Users/GJL/.rvm/gems/ruby-2.6.5/bin
     - /Users/GJL/.rvm/gems/ruby-2.6.5@global/bin
     - /Users/GJL/.rvm/rubies/ruby-2.6.5/bin
     - /Users/GJL/.rbenv/shims
     - /Users/GJL/.gem/ruby/2.6.0/bin
     - /usr/local/opt/ruby/bin
     - /Library/Frameworks/Python.framework/Versions/3.7/bin
     - /Library/Frameworks/Python.framework/Versions/3.7/bin
     - /usr/bin
     - /bin
     - /usr/sbin
     - /sbin
     - /usr/local/bin
     - /usr/local/lib/ruby/gems/1.9.1/gems/jekyll-2.5.2/bin
     - /Users/GJL/.rvm/bin

Notice the INSTALLATION DIRECTORY has the old Ruby version in it. Let’s update that to the latest version.

1
2
3
$ export GEM_HOME=/usr/GJL/.gem/ruby/2.7.0;
#
# This updates the INSTALLATION DIRECTORY to 2.7.0

Now let’s check the RubyGems environment again.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
$ gem environment
#
# This results in the following output.
RubyGems Environment:
  - RUBYGEMS VERSION: 3.1.4
  - RUBY VERSION: 2.7.2 (2020-10-01 patchlevel 137) [x86_64-darwin17]
  - INSTALLATION DIRECTORY: /usr/GJL/.gem/ruby/2.7.0
  - USER INSTALLATION DIRECTORY: /Users/GJL/.gem/ruby/2.7.0
  - RUBY EXECUTABLE: /usr/local/opt/ruby/bin/ruby
  - GIT EXECUTABLE: /usr/bin/git
  - EXECUTABLE DIRECTORY: /usr/GJL/.gem/ruby/2.7.0/bin
  - SPEC CACHE DIRECTORY: /Users/GJL/.gem/specs
  - SYSTEM CONFIGURATION DIRECTORY: /usr/local/Cellar/ruby/2.7.2/etc
  - RUBYGEMS PLATFORMS:
    - ruby
    - x86_64-darwin-17
  - GEM PATHS:
     - /usr/GJL/.gem/ruby/2.7.0
     - /Users/GJL/.rvm/gems/ruby-2.6.5
     - /Users/GJL/.rvm/rubies/ruby-2.6.5/lib/ruby/gems/2.6.0
  - GEM CONFIGURATION:
     - :update_sources => true
     - :verbose => true
     - :backtrace => false
     - :bulk_threshold => 1000
  - REMOTE SOURCES:
     - https://rubygems.org/
  - SHELL PATH:
     - /usr/local/opt/ruby/bin
     - /usr/local/opt/ruby/bin
     - /Users/GJL/.rvm/gems/ruby-2.6.5/bin
     - /Users/GJL/.rvm/gems/ruby-2.6.5@global/bin
     - /Users/GJL/.rvm/rubies/ruby-2.6.5/bin
     - /Users/GJL/.rbenv/shims
     - /Users/GJL/.gem/ruby/2.6.0/bin
     - /usr/local/opt/ruby/bin
     - /Library/Frameworks/Python.framework/Versions/3.7/bin
     - /Library/Frameworks/Python.framework/Versions/3.7/bin
     - /usr/bin
     - /bin
     - /usr/sbin
     - /sbin
     - /usr/local/bin
     - /usr/local/lib/ruby/gems/1.9.1/gems/jekyll-2.5.2/bin
     - /Users/GJL/.rvm/bin

Run again bundle install to ensure you have all the latest gems required by Jekyll.

1
2
3
$ bundle install
#
# This will fetch and install the required gems to use bundle

Run the Jekyll server

Now that you have installed the latest version of Ruby, Bundler and Jekyll, let’s run the Jekyll server.

Note that you need to run this command in the directory of your Jekyll project.

1
2
3
4
5
6
7
8
9
$ bundler exec jekyll serve
#
# This will start the Jekyll server and provide an HTTP address for a Jekyll website
#
$ Auto-regeneration: enabled for '<site path>'
$ Server address: http://127.0.0.1:4029//
$ Server running... press ctrl-c to stop.
#
# Enter in a browser the URL shown above

Now, open a browser and enter the Server address. A Jekyll website will load.

That’s it.

Not quite. I keep getting deprecation errors.

After running bundle exec jekyll serve, the Jekyll Server runs but I keep getting the following error:

.rvm/gems/ruby-2.7.0/gems/jekyll-4.0.0/lib/jekyll/tags/include.rb:179: warning: Using the last argument as keyword parameters is deprecated

Trying to fix that proved problematic. I first tried the following commmand.

gem update jekyll.

Didn’t work. Then I tried the following command.

sudo bundle update jekyll

Didn’t work but then I had to run this command again.

bundle install

Let’s see if this fixed it. Surprise, surprise. That fixed it. Now all I need to do is run the following command.

bundle exec jekyll serve

Now I have the right version of Jekyll, and Bundler. No idea why I had to do this, but it fixed whatever problem Jekyll was annoyed about, or maybe it swas something Bundler was upset about. Either way, they are both happy and so am I!