Stefan Boos

My personal GitHub pages

Follow me on GitHub

Generating Websites with Jekyll

Table of Contents generated with DocToc

Prerequisites

Ruby

Jekyll requires a recent Ruby installation. For macOS, it is recommended to use an installation different from the Ruby provided by Apple.

See Jekyll on macOS for instructions and Stackoverflow: You don’t have write permissions for the /Library/Ruby/Gems/2.3.0 directory. (mac user) if you’d like to have several Ruby versions installed in parallel.

For single version installation:

brew install ruby

# Register ruby and gem paths
echo 'export PATH="/opt/homebrew/opt/ruby/bin:/opt/homebrew/lib/ruby/gems/3.0.0/bin:$PATH"' >> ~/.zshrc

Jekyll

Then install bundler and jekyll as described on then Jekyll Homepage.

ruby --version

# Should be > 3 - otherwise see above
gem install bundler jekyll
bundle install

If you are on Ruby 3 with Jekyll 4.2.0, then an issue with webrick might hit you. To cure it, run

bundle add webrick

from inside the Jekyll site directory.

Local Development

To watch your changes while editing:

bundle exec jekyll serve --livereload

Troubleshooting - Upgrading Bundler and Gems

If you encounter an error like

$ bundle exec jekyll serve --livereload
/opt/homebrew/opt/ruby/bin/bundle:25:in `load': cannot load such file -- /opt/homebrew/lib/ruby/gems/3.1.0/gems/bundler-2.3.14/exe/bundle (LoadError)
        from /opt/homebrew/opt/ruby/bin/bundle:25:in `<main>'

and

$ ruby -v     
ruby 3.3.0 (2023-12-25 revision 5124f9ac75) [arm64-darwin23]

You might need to re-install the bundler

$ gem install bundler
Fetching bundler-2.3.21.gem
Successfully installed bundler-2.3.21
Parsing documentation for bundler-2.3.21
Installing ri documentation for bundler-2.3.21
Done installing documentation for bundler after 0 seconds
1 gem installed

If you see a message announcing a new release of RubyGems, then run the given update command and repeat the gem install bundler step.

Next, delete the Gemfile.lock

$ rm Gemfile.lock

and re-install your Ruby gems

$ bundle install

Liquid Template Language

Authentication and Restricted Access

The jekyll-auth module allows to restrict access. It uses GitHub OAuth and allows to manage user access via GitHub organizations and teams.

Note, that the Getting Started guide needs some further explanations. You can find the necessary details in my personal repository wonderbird / experiment-with-jekyll-auth. I have commented an issue for jekyll-auth in this context.

Further Information