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
If you’re using Ruby >= 2.3.0, go ahead and fetch the latest version of Jekyll:
gem update jekyll
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.
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
templateinstance is then rendered as previously, with respect to the
payloadpassed to it. You’ll therefore have to ensure that
payloadis not memoized or cached in your plugin instance.
If its a requirement that
templateyou get from the above step be different at all times, you can invoke
- template = site.liquid_renderer.file(path).parse(content) + template = Liquid::Template.parse(content)
Timezone in Windows
Timezone handling for Jekyll on Windows now requires
tzinfo-2.0 and above.
Simply add / update the gem listing in your
# Gemfile # Windows does not include zoneinfo files, so bundle the tzinfo-data gem # and associated library. gem "tzinfo-data", platforms: [:mingw, :mswin, :x64_mingw, :jruby] gem "tzinfo", "~> 2.0"
We’ve enhanced our default exclusion array. It now looks like the following:
# default excludes exclude: - .sass-cache/ - .jekyll-cache/ - gemfiles/ - Gemfile - Gemfile.lock - node_modules/ - vendor/bundle/ - vendor/cache/ - vendor/gems/ - vendor/ruby/
What’s new is that this array does not get overridden by the
in the user’s config file anymore. The user’s exclude entries simply get
added to the above default array (if the entry isn’t already excluded).
To forcibly “process” directories or files that have been excluded, list them
include array instead:
# overrides your excluded items configuration and the default include array ([".htaccess"]) include: - .htaccess - node_modules/uglifier/index.js
The above configuration directs Jekyll to handle only
while ignoring every other file in the
node_modules directory since that directory is
“excluded” by default.
Note that the default
include array still gets overridden by the
include array in your
config file. So, be sure to add
.htaccess to the list if you need that file to be
present in the generated site.
Did we miss something? Please click “Improve this page” above and add a section. Thanks!