111 lines
3.2 KiB
Markdown
111 lines
3.2 KiB
Markdown
---
|
|
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!*
|