Start a GitHub pages repo on Mac

I really enjoy using GitHub pages as website hosting service. However, I don't have any experience in developing Jekyll projects, and it's quite painful to set up a working starting point on Mac OS X 11 (Big Sur). I'll share some important tips I think to save your time hopefully. Trust me, it won't be as simple as it's described in Jekyll official documents.

The "Quick-start Instructions" won't work if you never work on Ruby projects on your Mac:

A simple example would be: you'll notice the latest version of Jekyll shows "V4.2.1", BUT in GitHub Pages dependency versions it's listing 3.9.0 instead:

If you are familiar with Semver, you'll know 4.0 and 3.0 are major releases with incompatible API changes. Okay, let's forget it for now since it won't be one of the big obstacles you are going to meet actually.

Firstly, make sure your Xcode is ready.

Before installing anything Jekyll related, you have to make sure Xcode development Command Line Tools is installed and linked. You can run the following command:

xcode-select --install

I will recommend you just simply launch Xcode instead. You may see the screen like this:

click "Install" to install it. After installed, double check it in your Xcode preferences:

Make sure "Command Line Tools" dropdown selects a version at least. If not, choose one from the list.

Homebrew and rbenv ease your life

I believe almost everyone starts installing Jekyll by using the following command showed in their official website:

gem install bundler jekyll

You are likely seeing all kinds of issues:

• Permission issues: you may wonder to use "sudo" instead
• Compiling issues: missing library or header files ("ERROR: Failed to build gem native extension", "'ruby/config.h' file not found", etc)

Let's leave permission issues later because if we don't have the current Ruby environment, installing anything above is a waste of time.

In their official documents, they suggest to install Homebrew which is brilliant, but later on they suggest to install Ruby 3.0 which is totally not necessary and will cause you some trouble later (Ruby 3.0 removes webrick). I would suggest if you don't have Homebrew installed, please install it. It's extremly useful across your entire developing life on Mac.

After Homebrew installed, we need to install rbenv instead:

# Install rbenv and ruby-build
brew install rbenv

# Set up rbenv integration with your shell
rbenv init

# Check your installation
curl -fsSL https://github.com/rbenv/rbenv-installer/raw/main/bin/rbenv-doctor | bash

Once you complete environment setups of rbenv, we can continue installing a new Ruby version now. Yes, a new version but not 3.0:

rbenv install 2.7.4
rbenv global 2.7.4
ruby -v
# should show something like ruby 2.7.4p191 (2021-07-07 revision a21a3b7d23) [x86_64-darwin20]

If "ruby -v" still gives you the old 2.6 version, try restarting your Mac Terminal to reload the bash profile.

Install Jekyll into current user

Now we can install Jekyll. We definitely don't want to install those libraries into global scope with "sudo". What we need is to make it work with current Mac user instead by adding "--user-install". Before doing this, we need to make sure the environment variable "$PATH" contains the current Ruby version we are using. We could either do:

# If you're using Zsh
echo 'export PATH="$HOME/.gem/ruby/2.7.4/bin:$PATH"' >> ~/.zshrc

# If you're using Bash
echo 'export PATH="$HOME/.gem/ruby/2.7.4/bin:$PATH"' >> ~/.bash_profile

in their doc, or directly editing your ".zshrc" or ".bash_profile". After relaunching Terminal, we can finally start installing it:

gem install --user-install bundler jekyll

Testing it out by:

jekyll -v

Oh you are seeing "4.2.1" instead of "3.9.0"? That's no big deal once we set our Jekyll project up.

Initialize GitHub pages repo

We are almost there. However, "jekyll new xxx" command will create a Jekyll 4 project instead, but GitHub pages will only accept Jekyll 3. Instead, we will manually create a new folder and write the following lines into "Gemfile" of it:

source "https://rubygems.org"
gem "github-pages", group: :jekyll_plugins

Now in the folder, we simply run:

bundle install

This will set up and install the required packages for GitHub pages with Jekyll 3.9 instead, and then when we need to execute "jekyll" command, we use "bundle exec jekyll" instead. For example:

bundle exec jekyll serve --livereload

Lastly

You are likely to see the following error when trying to "jekyll serve" your folder on Mac OS:

"`require': cannot load such file -- webrick"

Googling online, you may find out the following link as a resolution:

I have tested it out. It is not only appearing on Ruby 3.0 but also Ruby 2.7.

The solution is: to add "webrick" as one more dependency by running:

bundle add webrick