---
title: Upgrading from 3.x to 4.x
permalink: /docs/upgrading/3-to-4/
---

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

```sh
ruby -v
```

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

```sh
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`. <br/>
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:

  ```diff
  - 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`:

```ruby
# 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"
```

---

### Exclusion changes

We've enhanced our default exclusion array. It now looks like the following:

```yaml
# 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 `exclude` array
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
in the `include` array instead:

```yaml
# 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 `node_modules/uglifier/index.js`
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!*