Host your website with GitHub Pages. Use whatever Jekyll plugins you like — even fancy ones that Pages doesn’t support. The secret: build and deploy your Jekyll website with GitHub Actions. Here’s how.

Update 1 Oct 2022: GitHub now supports building Pages sites directly with Actions, and now provides an example workflows for Jekyll and many other static site generators. The workflow below builds on the Jekyll example, adding a step to install JPT’s dependencies.

GitHub Pages is a terrific way to host a website — especially if you’re already using GitHub. Sure, there are dedicated hosting services that offer more flexibility and more power. But Pages is built in, ready to serve public or even private static websites. It’s reliable, and you don’t need anything extra. Publishing is a matter of clicking a checkbox and pushing to a particular branch.¹

GitHub Pages supports Jekyll, the granddaddy of static site generators. You write in markdown text, and when you push your changes to GitHub, Jekyll combines your text with templates you’ve chosen, and publishes the resulting html website.

Pages allows a limited set of Jekyll plugins. It includes the basics for a typical blog — pagination, Atom feeds, sitemaps, SEO metatags, a selection of themes, and it will build sites like these automatically.

But what if you want to get fancier?

Maybe you’d like to use responsive images — and have Jekyll resize your graphics and generate the proper <picture> or <img srcset=""> tags automatically. Jekyll Picture Tag for responsive images works fabulously for this. Or maybe you’re using Jekyll’s collections data types, and need a more contemporary pagination plugin.

I found myself in this situation recently. In my case, I wanted to migrate a bunch of photos from Flickr. And both of those plugins aren’t supported by Pages’ Jekyll installation.

If you like me find yourself adding plugins like these to your Gemfile — well this post is for you.

  # not available with GitHub Pages:
  gem "jekyll-tagging-lite"
  gem "jekyll-paginate-v2"
  gem "jekyll_picture_tag"

Use Actions to BYOJS (Build your own Jekyll site)

You can use GitHub Actions to build and deploy a Jekyll site. But rather than GitHub’s built-in Jekyll processing, by using an action to do this, you can use any plugin you like.

In outline, here’s what’s needed to build a Jekyll static site.

1. Install Ruby and dependencies. Then install Jekyll and your plugins bundle install
2. Build your site jekyll build
3. Publish the site to GitHub pages git push origin gh-pages

You can do all of these from your local machine, of course. Manually. But GitHub Actions can do all of this automatically — every time you push code to main. That’s just like the built-in GitHub Pages workflow you may be familiar with.

To do this, switch your settings to use a custom Actions publishing workflow for Pages, and create a workflow like this one. You can use the Jekyll example workflow provided, just be sure to add the stuff in lines 28-30 here — JPT requires the libvips-tools library, which that step installs.

Commit this yaml file into your repository’s .github/workflows folder, and it will run every time new code is pushed to your main branch on GitHub.

It does the three steps above, but better than running on your computer, the workflow grabs a Linux runner from the cloud. The workflow installs Ruby and the libraries that JPT needs to resize images. Then it builds the Jekyll site and publishes the results to Pages. Boom.

See the step-by-step comments in the gist above.

GitHub publishes example workflows for many common static site generators like Gadsby, Hugh or Eleventy, and these techniques can be adapted for pretty much any statically-generated site.

Let me know how it works for you!