Skip to main content

This is an overview of the Ruby development environment you’ll need to understand to build Jekyll websites.

What is a Gem?

A Gem is a bundle of code you can include in Ruby projects. This allows you to take someone else’s code and drop it into your own project.

Jekyll itself is a Gem as well many Jekyll plugins including jekyll-feed, jekyll-seo-tag and jekyll-archives.

If you’re coming from Javascript, Gems are like npm. If you’re coming from Python, Gems are like pip.

What is a Gemfile?

A Gemfile is Ruby’s dependency management system. It’s a list of Gems you want your Ruby project to run. We use Gemfiles on Jekyll sites when you have Jekyll plugins.

If you’re coming from Javascript, a Gemfile is like package.json. If you’re coming from Python, a Gemfile is like requirements.txt or Pipfile.

What a Gemfile Looks Like

A Gemfile requires at least one source which tells your project where to download the Gems. With rare exception this will be rubygems.org.

You need the word “gem” followed by the name of the Gem.

The Gemfile for webniyom.com looks like this:

source 'https://rubygems.org'

gem 'jekyll'
gem 'liquid-c'

group :jekyll_plugins do
  gem 'jekyll-feed'
  gem 'jekyll-sitemap'
  gem 'jekyll-autoprefixer'
  gem 'jekyll-include-cache'
  gem 'jekyll-paginate-v2'
end

I’ve worked on some projects that required a specific version of Jekyll. Here is an example from one of those projects:

source 'https://rubygems.org'

gem 'jekyll', '3.1.6'

gem 'i18n'
gem 'xkeys'
gem 'jekyll-sitemap'

Bundler and How to Use It

Bundler is the program that reads the Gemfile and downloads the Gems.

When you create or change a Gemfile, you need to run bundle install which performs two tasks:

  1. Creates a Gemfile.lock file if it doesn’t already exist. (This file includes all the Gems in the Gemfile with version numbers even if they weren’t specified. If checked-in to your repo, this ensures everyone working on the project has the same gem versions. In my experience this is rarely used for Jekyll sites.)
  2. Downloads the gems in Gemfile.lock.

If you are using the latest versions of all gems, you can serve a jekyll site like this:

  jekyll serve

When you’re using a Gemfile with specific versions, you need to run Jekyll with Bundler. You might have multiple versions of Jekyll installed and if you run jekyll serve, it might use the wrong version. You can solve this using bundle exec which makes only the Gems in the Gemfile available. For example, if you want to run jekyll serve you’d run:

  bundle exec jekyll serve