Remember that 2017 post where I complained about Jekyll tooling? Here I am, nearly nine years later, finally doing something about it.
Better late than never, I suppose.
I decided to update some styles on this blog. Simple enough. Crack open the SCSS files, make some tweaks, done. Except I wanted to use modern Sass features - @use and @forward, the module system that’s been around since 2019. Turns out the github-pages gem locks you to Jekyll 3.x, which uses the old Ruby Sass compiler. Deprecated for years.
The fix: ditch the github-pages gem entirely and upgrade to Jekyll 4.x.
What that means in practice:
The old way (GitHub Pages classic):
- Use the
github-pagesgem - GitHub builds your site automatically
- Stuck on Jekyll 3.x forever
The new way (Jekyll 4 + GitHub Actions):
- Use
jekyllgem directly (version 4.x) - GitHub Actions builds your site
- Modern Sass with dart-sass
- Actually maintained tooling
The migration wasn’t too painful. Main gotcha: dart-sass deprecated the / operator for division. All those $spacing-unit / 2 declarations had to become $spacing-unit * 0.5. Tedious, but find-and-replace is a thing. LLMs too.
For the GitHub Actions part:
- Add a workflow file (
.github/workflows/jekyll.yml) - Go to your repo’s Settings → Pages
- Change the source from “Deploy from a branch” to “GitHub Actions”
The workflow itself is straightforward. Trigger on push to master/main:
on:
push:
branches: ["master", "main"]
workflow_dispatch:
Build job sets up Ruby, installs dependencies via bundler, builds the site:
- name: Setup Ruby
uses: ruby/setup-ruby@v1
with:
ruby-version: '3.3'
bundler-cache: true
- name: Build with Jekyll
run: bundle exec jekyll build --baseurl "$"
env:
JEKYLL_ENV: production
Then deploy to GitHub Pages:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4
Push your changes, the workflow handles the rest.
Was it worth the effort? Ask me after I’ve actually updated those styles I originally set out to change.
-J