How to Install Ruby and Jekyll with Homebrew on macOS.

You may find Chinese articles here if you read through my blog. I plan to move all my Chinese content to a new blog/website. I'm looking for free and customizable options. After some research, I want to give Github Pages with Jekyll a try.

I follow Jekyll's installation instructions to install it on my local device for further testing. During the installation, my terminal keeps prompting error messages. I had to spend extra time on Google and find the solution to fix it.

My installation guide will focus on an Intel-based Mac.

Avoid the macOS pre-installed Ruby.

Jekyll is using Ruby Programming language to develop it. Therefore, Ruby needs to install on the local device first.

macOS 12 shipped with Ruby 2.6.8, but I will avoid touching it after reading the article from Don't use system Ruby.

I will list 3 of the reasons below, which I learned from the article.

1. Pre-installed Ruby is not for the user.
   Other parts of the operating system may be using pre-installed Ruby with specific requirements. It's designed for the operating system to use, not the user.
2. Pre-installed Ruby is not able to modify.
   Since the operating system may depend on pre-installed Ruby, any pre-installed Ruby modification may cause the operating system to break down.
   FYI: you can modify the pre-installed Ruby by adding the "sudo" command, but it's not recommended and violate the system's security.
3. Pre-installed Ruby can change any time.
   Operating system maintainers like Apple can make any changes with the pre-installed Ruby. Upgrade, downgrade, or remove the entire Ruby binary file may be happening on a newer system update. No guarantee from the system maintainer.

Which Ruby is in use? System Ruby or the user Ruby?

Type which ruby in the terminal and hit the Enter key.

    $ which ruby
    /usr/bin/ruby
  

This command shows the path of Ruby binary in use. If, the terminal return /usr/bin/ruby. Then, it's using the pre-installed Ruby.

How to check the Ruby version?

Type ruby -v in the terminal and hit the Enter key.

    $ ruby -v
    ruby 2.6.8
  

How to Install Ruby for the user/development?

As mentioned above, we should install Ruby on our own. First, I will install the package manager, Homebrew. Then, I will use Homebrew to install Ruby.

Type xcode-select --install in the terminal and hit the enter key.

    $ xcode-select --install
  

Next, Type export SDKROOT = $(xcrun --show-sdk-path) in the terminal and hit the enter key to avoid jekyll failing installation.

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

How to install Homebrew?

Type /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh) in the terminal and hit the enter key in terminal.

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

What if the installation encounters issues?

Type brew doctor in the terminal and hit the enter key.

    $ brew doctor
  

This command will check the system for potential issues. One of the issues I encounter is Homebrew's unable to find any formula.

I run a brew doctor and find out the Homebrew repository issue on my local device. I'm using the last resort command brew update-reset to reset EVERYTHING. Please use this command with caution. Try to understand the error messages brought up by the brew doctor command. Then, Google searches the error messages to solve the issues one by one.

How to Install Ruby and configure the shell environment?

Type brew install ruby in the terminal and hit the enter key.

    $ brew install ruby
  

Once the Ruby installation is complete, we need to set the Ruby binary path. It allows the terminal(shell) to use the Homebrew Ruby instead of the Pre-installed Ruby.

Open the ~/.zshrc file in the text editor using the command open -e ~/.zshrc.

    $ open ~/.zshrc
  

Then, paste the code below at the end of the ~/.zshrc file. Save it and exit.

    if [ -d "/usr/local/opt/ruby/bin" ]; then 

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

      export PATH=`gem environment gemdir`/bin:$PATH 

    fi
  

After, try to close and reopen the terminal.

Now, you can type which ruby and ruby -v in the terminal to check which Ruby binary and version are in use.

Check Ruby binary location that in use:

    $ which ruby 
    /usr/local/opt/ruby/bin/ruby
  

Check Ruby version:

    $ ruby -v
    ruby 3.0.3p157
  

How to install Jekyll and Bundler?

First, we need to know Ruby's Gems. Gems are the functionality/library developed by Ruby's community. Jekyll is one of the Gems. Hence, we need to use Gems to install Jekyll.

Also, we need to install Bundler. Bundler is a Gem to manage the project dependencies. So, we can escape from the Dependency Hell.

Type gem install jekyll bundler in the terminal and hit the enter key to install both Jekyll and Bundler.

 
    $ gem install jekyll bundler 
  

Try Jekyll now.

After all, we can use Jekyll to create and start the site on the local device.

Type and enter jekyll new myblog in the terminal to create a jekyll site.

 
    $ jekyll new myblog 
  

Type and enter cd myblog to change the current terminal directory into the "myblog" directory.

 
    $ cd myblog 
  

Please add the Webrick gem(dependency) for the local device that uses Ruby version 3.0 and higher. Without Webrick, it will be unable to build and start serving the site.

    $ gem webrick
  

Type bundle exec jekyll serve to build and start the server.

    $ bundle exec jekyll serve
  

References:

• Don't use system Ruby
• Jekyll on macOS | Jekyll • Simple, blog-aware, static sites
• Brew Install Ruby · Mac Install Guide