This site is a work-in-progress. Some of the information is incomplete and may not work as described. See the homepage for details.

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

Table of Contents:

What is a Gem?

If you’re coming from Javascript or Python you’ll know these as packages. 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 are many Jekyll plugins including jekyll-feed, jekyll-seo-tag and jekyll-archives.

What is a Gemfile?

A Gemfile is a list of gems you want your Ruby project to run. If you’re coming from Javascript, 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 to include them in the project.

The Gemfile for jekyllfieldguide.com looks like this:

source 'https://rubygems.org'

gem 'jekyll'

group :jekyll_plugins do
  gem 'jekyll-autoprefixer'
end

gem 'execjs', '2.7' # Add execjs v2.7 as there is an error in v2.8
gem 'webrick' # Add webrick gem for local development

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 'liquid-c'
gem 'i18n'
gem 'jekyll-sitemap'

Using gem 'jekyll', '3.1.6' will install version 3.1.6 of Jekyll when your run Bundler.

Bundler and How to Use It

Bundler is the program that reads the Gemfile and downloads and manages the gems.

When you create or change a Gemfile, you need to run bundle in the terminal (running bundle without specifying an option is the same as running bundle install). This will perform two tasks:

  1. It 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, as well as all the dependencies for those gems. If committed to your repo, this ensures everyone working on the project has the same gem versions.)
  2. It downloads the gems in Gemfile.lock.

If you installed Jekyll globally by using the terminal command gem install jekyll, you can run Jekyll using the command jekyll build or jekyll serve. If you installed Jekyll only via Bundler, then the “naked” jekyll command won’t work. By installing with Bundler, it is only accessible when you run bundle exec jekyll .... Using the bundle exec command also ensures you are using the versions specified in your Gemfile when it is also installed globally.

Grouping Your Dependencies

You’ll notice in the “What a Gemfile Looks Like” section above that one of the example Gemfiles has a jekyll_plugins group and the other does not. There are times when developing a complex site that you may have problems and want to run your build command without plugins. This is a way to help with that. In the example above I could run bundle install --without jekyll_plugins and none of the gems in that group would be used. This can be helpful when troubleshooting.

Creating a group can also be useful for local development. It is rare that you should need certain plugins during local development. Adding them to a group like below and running bundle install --without production could improve site build times.

group :production do
  gem 'jekyll-feed'
  gem 'jekyll-sitemap'
end

One thing to note is, this exclusion state will persist. You can’t get the jekyll_plugins group or the production group to install by just running bundle install again. There is some command line-fu you can use to undo the --without declaration and get Bundler to install your jekyll_plugins group once again, but the easiest way is to delete the .bundle directory that was created by running the command.

Bundler Docs

The information above is the most common knowledge you’ll need in a Jekyll environment. There is a load more you may need to know about Ruby gems and Bundler for different Ruby projects. Check https://guides.rubygems.org/ and https://bundler.io/docs.html for more.