Using Jekyll 4 with GitHub Pages
by James Armes (they/them)
This site is built using Jekyll and hosted on GitHub Pages. I’ve been using this setup for some time, since switching from a Drupal site (which was overkill for this small blog and the little traffic it receives) and paid hosting. Until recently, I used the default setup on GitHub Pages which uses jekyll 3.9.2. When I decided to hit the reset button, I saw that Jekyll 4.0.0 was released in 2019 (nearly four years ago!) and with the release of 4.3.0, the 3.9.x releases were officially moved to security updates only.
GitHub has, unfortunately, made no mention of updating the supported version used for GitHub Pages. However, at its core, Pages is just a static hosting service with some support for building from Jekyll. I opted to move forward using the latest version of Jekyll, knowing that I would have to handle building the site myself.
Jekyll 4
Jekyll 4.0.0 was a complete rewrite of the codebase. This rewrite dropped support for older ruby versions, removed dependencies that were no longer maintained, and included a number of enhancements.
Some of the major enhancements in the 4.x releases:
- Many improvements to caching
- A new Sass processor
- An updated markdown engine
- Better handling of links
- Configuration options for gem-based themes
- Support for logical operators in conditional expressions
- Support for Ruby 3.x
- Support for CSV data
There’s much more, and of course all of the bug fixes and security updates included in every release. Checkout the releases page for more details.
Deploying Jekyll 4 on GitHub Pages
To deploy Jekyll 4 on GitHub Pages, you’ll need to use GitHub Actions. GitHub Actions is a CI/CD Continuous integration and continous delivery service that allows you to automate tasks in your workflow. You can use it to build, test, and deploy your code similar to other systems like Jenkins or CircleCI.
Workflows are configured in YAML files in the .github/workflows directory of
your repository. You can have multiple workflows, each of which can have one or
more jobs, which in turn contain one or more steps. For our purposes, we need
one workflow with two jobs, one to build the site and another to deploy it to
GitHub Pages.
For example, the workflow file for this site looks like this:
# This workflow uses actions that are not certified by GitHub.
name: Deploy Jekyll site to Pages
on:
push:
branches: main
# Allows you to run this workflow manually from the Actions tab
workflow_dispatch:
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
contents: read
pages: write
id-token: write
# Allow one concurrent deployment
concurrency:
group: pages
cancel-in-progress: true
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v3
- name: Setup Ruby
uses: ruby/setup-ruby@v1
with:
bundler-cache: true
- name: Setup Pages
id: pages
uses: actions/configure-pages@v2
- name: Build with Jekyll
# Outputs to the './_site' directory by default
run: bundle exec jekyll build --baseurl "$"
env:
JEKYLL_ENV: production
- name: Upload artifact
# Automatically uploads an artifact from the './_site' directory by default
uses: actions/upload-pages-artifact@v1
# Deployment job
deploy:
environment:
name: github-pages
url: $
runs-on: ubuntu-latest
needs: build
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v1
Now, anytime I push a change to my main branch, the site is built and deployed
automatically!
