Jekyll Site: Setup

Last updated Tuesday 29 October 2024.

Most relevant documentation links

• Jekyll Quickstart

• GitHub Pages dependencies

• GitHub Actions: Jekyll

Important tribal knowledge

Traditionally, "GitHub Pages" support is a strongly locked-down affair. This created many conflicts with Jekyll, various Gems, and GitHub Pages plugins. The GitHub Pages Actions workflow is meant to partially alleviate the issue.

I use Linux and Mac OS X. Linux users need no help but I will document the Mac OS X setup.

Mac OS X Setup

Use asdf to install ruby:

#!/usr/bin/env zsh

brew update && brew upgrade --greedy \
&& brew install coreutils curl asdf

Install latest ruby using asdf

---

Explanation 1:

Please remember that asdf delegates to resource managers called plugins

asdf manage tool artifacts via dedicated plugins that fully control the lifecycle or SDKs they manage.

• Here is the 'Getting Started' guide for asdf;

• documentation on core functionality;

• and, TL;DR on plugins and version management.

• Example: To list all plugins, use:

asdf plugin list all

• Example: To upgrade all plugins, use:

asdf plugin update --all

---

Step 1: Install ruby plugin (see the ruby home repository to get the sense of plugins):

asdf plugin add ruby

Step 2: Then, install the latest ruby:

asdf install ruby latest

Step 3: Verify:

asdf current

Install Jekyll and GitHub Pages dependencies

Navigate into your project docs directory before working on Jekyll site!

Follow the Jekyll Quickstart documentation.

cd site
gem install jekyll bundler
jekyll new site --force
bundle install && bundle exec jekyll serve -wolIVt

That’s it!

We have then modified our site to apply Minimal Mistakes Jekyll theme.