jekyll/docs/_docs/upgrading/3-to-4.md

title	permalink
Upgrading from 3.x to 4.x	/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

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)
  

---

Exclusion changes

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

# 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 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:

  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!