Ruby, Gems, Bundler, and the `Gemfile`

Ruby, Gems, Bundler, and the Gemfile

Jekyll is not a standalone mystery executable that appeared on your computer.

Jekyll is distributed through the Ruby ecosystem.

You do not need to become a Ruby programmer to use Jekyll well, but you do need to understand the dependency chain you are running.

The dependency chain

RUBY
  ↓
RUBYGEMS
  ↓
GEMS
  ↓
BUNDLER
  ↓
GEMFILE + GEMFILE.LOCK
  ↓
JEKYLL COMMAND

Ruby

Ruby is the programming language/runtime Jekyll is built with.

RubyGems

RubyGems is Ruby's package system. Packages are called gems.

Jekyll itself is installed as a gem.

Bundler

Bundler manages the specific gem dependencies for a project.

The official Jekyll tutorial recommends using a Gemfile so the project declares what it depends on.

Build a dependency record

From a project folder, a common setup is:

bundle init

Then add Jekyll:

bundle add jekyll

A simplified Gemfile might look like:

source "https://rubygems.org"

gem "jekyll"

After Bundler resolves and installs dependencies, a Gemfile.lock records the resolved versions.

The important idea is not memorizing commands.

The important idea is reproducibility.

Someone else should be able to clone the project, install the declared dependencies, and run the same build without guessing what you had installed globally.

Why bundle exec matters

You will often run:

bundle exec jekyll build

rather than only:

jekyll build

bundle exec runs the command inside the dependency environment described by the project's bundle.

That reduces the chance that a different globally installed Jekyll or plugin version silently changes the build.

Guided failure: command not found

Suppose you type:

jekyll serve

and receive a command-not-found error.

Bad troubleshooting:

Jekyll is broken.

Better questions:

1. Is Ruby installed?
2. Is Bundler installed?
3. Has the project bundle been installed?
4. Am I inside the project directory?
5. Does bundle exec jekyll --version work?

The failure could be at the environment layer before Jekyll even receives a build request.

Inspect your environment

Use commands appropriate to your environment:

ruby --version
bundle --version
bundle exec jekyll --version

Record the output.

If your classroom image already includes the environment, do not reinstall system software simply because this lesson shows installation commands. Read what is already there first.

The project rule

Keep the dependency files with the source repository.

At minimum, know the purpose of:

Gemfile
Gemfile.lock

Later, when deployment behaves differently from your laptop, these files become evidence.

Checkpoint

Explain this in your own words:

Why can "it works on my computer" be a dependency-management problem?

Then create a dependency evidence block:

Ruby version:
Bundler version:
Jekyll version:
Gemfile present: yes/no
Gemfile.lock present: yes/no

Keep it with the portfolio.