How To Install Jekyll on a Mac, the Easy Way

It pains my heart to see folks struggle to install Jekyll, through no fault of their own. Some people spend DAYS trying to figure it out. They ask on the Jekyll Forum, Stack Overflow, and other sites, where well-meaning people try to help but unfortunately provide incorrect or outdated solutions. It shouldn't be this frustrating!

The main reason people struggle is due to a combination of overly complicated manual installation instructions, incomplete, hard-to-read troubleshooting guides, and inconsistent advice. The main thing that is not clear to beginners is that they first need to set up a proper Ruby environment. Once that's done, installing any Ruby gem is a breeze. The problem is that there are various ways to install Ruby on a Mac, but the Ruby community hasn't adopted a consistent choice.

I believe in simplifying things as much as possible, so that people who are new to Ruby don't have to suffer. This is why I wrote a script that provides a working Ruby development environment on a Mac, using a Ruby manager, which I strongly believe should be the only way to install Ruby. It sets people up for success for the long term. My script can be run safely multiple times. It only installs what you don't already have, and it upgrades any outdated tools. It also automatically detects which shell you are using, and configures your shell startup file with the proper PATH and commands. That way, you don't run into the "jekyll: command not found" error.

Once you run my script and you see "All done!" in your Terminal, make sure to quit and restart Terminal, then you should be able to use Jekyll right away because my script installs it for you. You can verify the jekyll command is working by checking the Jekyll version:

jekyll -v

Or you can look up all the possible commands:

jekyll help

Create a new Jekyll site

Create a folder to hold your Jekyll site and navigate to it. Optionally replace testing-jekyll with your preferred folder name.

mkdir ~/testing-jekyll && cd ~/testing-jekyll

Switch to Ruby 2.7.2. At the time of this writing, Jekyll doesn't work out of the box with Ruby 3.0.0.

chruby 2.7.2

Create a new Jekyll site:

jekyll new .

Run the server:

bundle exec jekyll serve

You should now be able to view your site at http://localhost:4000.

This is just a quick way to confirm that you can create and view a Jekyll site on your computer. Next, you should read my guide for creating a new Jekyll site and publishing it on GitHub Pages.