↓ Skip to main content
Chandler Thompson
  1. Posts/

Getting started with Jekyll on macOS

·937 words·5 mins·
Site Mechanics
Table of Contents

So you want to set up a sleek new Jekyll site, but you’re staring at your terminal wondering why Ruby, Bundler, and a bunch of configuration files are involved. Fear not, intrepid site-builder, because I’ve got your back. Let’s walk through how to set up Ruby using chruby and Homebrew, install Bundler, and get Jekyll running smoothly on macOS.

Why Ruby, Bundler, and chruby?
#

Before diving in, here’s the TL;DR on why you need these tools:

  • Ruby: Jekyll is written in Ruby, so we need Ruby installed to run it.
  • chruby: A lightweight Ruby version manager that makes switching between Ruby versions a breeze.
  • Bundler: Manages Ruby gem dependencies so your Jekyll site runs the same way on every machine.
  • Homebrew: A macOS package manager that simplifies the installation of all the above.

Installing Ruby with Homebrew and chruby
#

Step 1: Install Homebrew
#

If you don’t already have Homebrew, install it. I have an installation guide. The short version is paste the below command into your terminal:

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

After installation, make sure Homebrew is set up:

brew doctor
brew update

Step 2: Install chruby and ruby-install
#

Use Homebrew to install chruby and ruby-install:

brew install chruby ruby-install

Step 3: Install Ruby
#

Install the latest stable Ruby version supported by Jekyll:

ruby-install ruby 3.3.5

Once installed, configure your shell to use chruby. Add the following lines to your shell’s configuration file (e.g., ~/.zshrc for Zsh users or ~/.bash_profile for Bash users) — the kind of config worth keeping in your dotfiles:

echo "source $(brew --prefix)/opt/chruby/share/chruby/chruby.sh" >> ~/.zshrc
echo "source $(brew --prefix)/opt/chruby/share/chruby/auto.sh" >> ~/.zshrc
echo "chruby ruby-3.3.5" >> ~/.zshrc

Replace .zshrc with .bash_profile if you use Bash. Restart your terminal to apply the changes, and verify the Ruby installation:

ruby -v

You should see something like ruby 3.3.5 (2024-09-03 revision ef084cc8f4).

Installing Bundler
#

Bundler is essential for managing Jekyll’s dependencies. Install it globally:

gem install bundler

To confirm the installation:

bundle -v

Setting up a minimal Jekyll site
#

Step 1: Install Jekyll
#

Now that Ruby and Bundler are set up, install Jekyll:

gem install jekyll

Step 2: Create a new Jekyll site
#

Navigate to the directory where you want your site and run:

jekyll new my-awesome-site

This command generates a new Jekyll site with a basic configuration.

Step 3: Run the site locally
#

Navigate into your site’s directory:

cd my-awesome-site

Install the site’s dependencies using Bundler:

bundle install

Start the local Jekyll server:

bundle exec jekyll serve --livereload

The --livereload option automatically refreshes your browser when you make changes to the source files, enhancing your development workflow. Visit http://localhost:4000 in your browser, and boom! Your site is live locally.

Customizing Jekyll configuration
#

Your site’s configuration lives in _config.yml. Here’s an example of how to customize the default settings provided by Jekyll’s Minima theme:

title: "Getting started with Jekyll on macOS"
email: "me@example.com"
description: >-
  A personal blog about tech, life, and other adventures.
baseurl: "" # The subpath of your site, e.g., /blog
url: "https://myawesomeblog.com" # The base hostname & protocol for your site

twitter_username: my_twitter_handle
github_username:  my_github_username

# Build settings
theme: minima
plugins:
  - jekyll-feed

Key settings explained:
#

  • title: The title of your site, which appears in the browser tab and header.

  • email: Your email address, displayed in the footer if configured.

  • description: A brief description of your site for SEO and metadata purposes.

  • baseurl and url: Essential for setting up the correct paths for assets and links when deploying your site.

  • Social Links (twitter_username, github_username): These are used by the Minima theme to link to your social profiles in the footer.

Make sure to save your changes and restart the Jekyll server to apply them.

For more details on configuration options, check out the Jekyll Configuration documentation.

Version control with Git
#

One of the great things about Jekyll is there’s no database. All content and site structure are files that a Git repository can version. Using a repository is optional but recommended. You can learn more about using Git by reading the Git Handbook.

To initialize a Git repository in your project directory:

git init
git add .
git commit -m "Initial commit"

This setup allows you to track changes, collaborate with others, and deploy your site efficiently.

Troubleshooting tips
#

  1. Ruby version issues: Ensure you’re using the correct Ruby version with chruby.
  2. Permission errors: Use a Ruby version installed in your home directory to avoid sudo.
  3. Dependency conflicts: Delete Gemfile.lock and re-run bundle install.
  4. LiveReload not working: Ensure you’re using the --livereload flag when running the server. If issues persist, check for browser extensions or firewall settings that might block LiveReload.

Closing notes
#

That’s a working Jekyll setup: Ruby pinned with chruby, dependencies handled by Bundler, and a site serving locally with live reload. The payoff of the file-based, no-database approach is that everything you just built is plain text a Git repo can track and a host can deploy on every push.

A note from the future: this blog ran on Jekyll for years before I moved it to Hugo. The Ruby-toolchain setup here is still the right way to start a Jekyll site, but if you’re choosing a static-site generator today, it’s worth weighing the Go-based alternative too. I wrote up the Hugo version of my TIL workflow after the switch.

Additional resources
#

Chandler Thompson
Author
Chandler Thompson
I lead engineering teams and coach the people who run them. This is where I write down what actually worked.

Related