Upgrading from 3.x to 4.x

Upgrading from an older version of Jekyll? A few things have changed in Jekyll 4 that you’ll want to know about.

Before we dive in, you need to have at least Ruby 2.3.0 installed. Run the following in your terminal to check

ruby -v

If you’re using Ruby >= 2.3.0, go ahead and fetch the latest version of Jekyll:

gem update jekyll

Template rendering

We’ve slightly altered the way Jekyll parses and renders your various templates to improve the overall build times. Jekyll now parses a template once, caches it internally and then renders the parsed template multiple times as required by your pages and documents.

The downside to this is that some of the community-authored plugins may not work as they previously used to.

For Plugin-authors

  • If your plugin depends on the following code: site.liquid_renderer.file(path).parse(content), note that the return value (template, an instance of Liquid::Template), from that line will always be the same object for a given path.
    The template instance is then rendered as previously, with respect to the payload passed to it. You’ll therefore have to ensure that payload is not memoized or cached in your plugin instance.

  • If its a requirement that template you get from the above step be different at all times, you can invoke Liquid::Template directly:

    - template = site.liquid_renderer.file(path).parse(content)
    + template = Liquid::Template.parse(content)

Did we miss something? Please click “Improve this page” above and add a section. Thanks!