Jekyll

Table of contents
  1. Ruby installation with rbenv
  2. Install Jekyll
  3. Create a Jekyll blog
  4. Bundler / Gemfile
    1. Install gems listed in Gemfile
    2. Adding gems to project
    3. Removing gems
    4. Execute a command in the context of the bundle

Ruby installation with rbenv

I’ve decided to use rbenv only because I didn’t want to mess with the system ruby that comes with macOS (I am currently using Catalina).

Assuming you have Homebrew installed.

# Install rbenv and ruby-build
brew install rbenv 

# Set up rbenv integration with your shell
rbenv init
# Then follow the instruction that appears on screen

# rbenv init will ask you to add the following to .zshrc
eval "$(rbenv init - zsh)"

Now that you have installed rbenv, create a folder that will contain your Jekyll site. I will refer to the folder as blog. Once created, move into blog.

cd blog
# List latest stable versions
rbenv install -l
# I chose 3.0.2
rbenv install 3.0.2
rbenv rehash
# Following creates .ruby-version in cwd
rbenv local 3.0.2
# Confirm ruby version in folder
ruby -v

All the ruby versions are installed in ~/.rbenv.

Install Jekyll

Before installing the gems, check where they are being installed via

# Refer to INSTALLATION DIRECTORY / GEM PATHS
gem env
# OR
gem env home

Rest of the stuff are just my preferences/me being a clean freak.

Now, the Jekyll documentation tells you to do a local install with the --user-install flag.

If you’re not using rbenv this is indeed more desirable as it installs your gems to your home directory (like ~/.gem).

However, for my purpose and with rbenv it was unnecessary.

As you’ll notice by inspecting the gem env outputs, the global install directory (INSTALLATION DIRECTORY) is already in your home directory (~/.rbenv/versions/...).

On the other hand, the user install directory (USER INSTALLATION DIRECTORY) is set to some local folder (~/.local/share/gem/ruby/...).

I personally prefer having all the packages contained in ~/.rbenv, so I simply chose to omit --user-install and do:

End of me being a freak.

gem install jekyll bundler

Create a Jekyll blog

First create a new Jekyll project by

# Assuming you're still in the blog folder
jekyll new .

It will create a default website you can test locally.

# Will generate a static html site in _site
bundle exec jekyll serve

# With live-reloading
bundle exec jekyll serve --livereload

If you get any errors regarding webrick: cannot load such file -- webrick (LoadError), add webrick by bundle add webrick. This is due to ruby 3 excluding webrick as a default bundled gem.

Bundler / Gemfile

Think of the bundler as the npm/yarn of Ruby and Gemfile as the package.json of Node projects.

When you create a new Jekyll project with jekyll new, a Gemfile is automatically created.

This Gemfile will list the basic gem dependencies to create a basic Jekyll site.

Install gems listed in Gemfile

If there already exists a Gemfile, you can download all the necessary gems for this project by:

bundle install

These gems are usually installed in the same place they would be when you call gem install.

Exact location can be confirmed by bundle show <gem-name>.

Adding gems to project

When you need to add another gem for your project, you can either:

  • Type it out yourself in Gemfile
# Gemfile
gem "just-the-docs"

Then,

bundle install

OR

  • Use bundle add
bundle add just-the-docs

If the gems already exist in system, it’ll just use that. If they don’t already, it will download the gem for you.

Removing gems

When you no longer need a gem for the project,

bundle remove just-the-docs

This doesn’t remove the gem from the system. Only removes it from your project’s Gemfile.

Execute a command in the context of the bundle

Every bundled gem will be made available in the context of the command you wish to execute even if these gems are not in the executable path.

bundle exec jekyll build

References: