142 lines
4.4 KiB
Markdown
142 lines
4.4 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)
|
|
```
|
|
|
|
---
|
|
|
|
### 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.
|
|
|
|
---
|
|
|
|
### kramdown v2
|
|
|
|
Jekyll has dropped support for `kramdown-1.x` entirely.
|
|
|
|
From [`v2.0` onwards](https://kramdown.gettalong.org/news.html#kramdown-200-released) kramdown requires
|
|
specific extensions to be additionally installed to use certain features are desired outside of kramdown's
|
|
core functionality.
|
|
|
|
Out of all the extensions listed in the report linked above, gem `kramdown-parser-gfm` is automatically
|
|
installed along with Jekyll 4.0. The remaining extensions will have to be manually installed by the user
|
|
depending on desired funtionality, by listing the extension's gem-name in their `Gemfile`.
|
|
|
|
Notes:
|
|
* `kramdown-converter-pdf` will be ignored by Jekyll Core. To have Jekyll convert Markdown to PDF
|
|
you'll have to depend on a plugin that subclasses `Jekyll::Converter` with the
|
|
[required methods]({% link _docs/plugins/converters.md %}).
|
|
|
|
For example:
|
|
|
|
```ruby
|
|
module Jekyll
|
|
External.require_with_graceful_fail "kramdown-converter-pdf"
|
|
|
|
class Markdown2PDF < Converter
|
|
safe true
|
|
priority :low
|
|
|
|
def matches(ext)
|
|
# match only files that have an extension exactly ".markdown"
|
|
ext =~ /^\.markdown$/
|
|
end
|
|
|
|
def convert(content)
|
|
Kramdown::Document.new(content).to_pdf
|
|
end
|
|
|
|
def output_ext
|
|
".pdf"
|
|
end
|
|
end
|
|
end
|
|
```
|
|
* Vendors that provide a versioned Jekyll Environment Image (e.g. Docker Image, GitHub Pages, etc)
|
|
will have to manually whitelist kramdown's extension gems in their distributions for Jekyll 4.0.
|
|
|
|
---
|
|
|
|
*Did we miss something? Please click "Improve this page" above and add a section. Thanks!*
|