Using Jekyll 4 with GitHub Pages

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 continuous 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:

.github/workflows/deploy.yml

# 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!