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?
- What is a Gemfile?
- What a Gemfile Looks Like
- Bundler and How to Use It
- Grouping Your Dependencies
- Bundler Docs
What is a Gem?
What is a Gemfile?
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'
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:
- It creates a
Gemfile.lockfile if it doesn’t already exist. (This file includes all the gems in the
Gemfilewith 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.)
- It downloads the gems in
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.
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.