Improve this page

Upgrading from 2.x to 3.x

Upgrading from an older version of Jekyll? A few things have changed in 3.0 that you’ll want to know about.

Before we dive in, go ahead and fetch the latest version of Jekyll:

$ gem update jekyll

Diving in

Want to get a new Jekyll site up and running quickly? Simply run jekyll new SITENAME to create a new folder with a bare bones Jekyll site.

site.collections has changed

In 2.x, your iterations over site.collections yielded an array with the collection label and the collection object as the first and second items, respectively. In 3.x, this complication has been removed and iterations now yield simply the collection object. A simple conversion must be made in your templates:

• collection[0] becomes collection.label
• collection[1] becomes collection

When iterating over site.collections, ensure the above conversions are made.

Dropped dependencies

We dropped a number of dependencies the Core Team felt were optional. As such, in 3.0, they must be explicitly installed and included if you use any of the features. They are:

• jekyll-paginate – Jekyll’s pagination solution from days past
• jekyll-coffeescript – processing of CoffeeScript
• jekyll-gist – the gist Liquid tag
• pygments.rb – the Pygments highlighter
• redcarpet – the Markdown processor
• toml – an alternative to YAML for configuration files
• classifier-reborn – for site.related_posts

Future posts

A seeming feature regression in 2.x, the --future flag was automatically enabled. The future flag allows post authors to give the post a date in the future and to have it excluded from the build until the system time is equal or after the post time. In Jekyll 3, this has been corrected. Now, --future is disabled by default. This means you will need to include --future if you want your future-dated posts to generate when running jekyll build or jekyll serve.

Layout metadata

Introducing: layout. In Jekyll 2 and below, any metadata in the layout was munged onto the page variable in Liquid. This caused a lot of confusion in the way the data was merged and some unexpected behaviour. In Jekyll 3, all layout data is accessible via layout in Liquid. For example, if your layout has class: my-layout in its YAML front matter, then the layout can access that via {{ layout.class }}.

Syntax highlighter changed

For the first time, the default syntax highlighter has changed for the highlight tag and for backtick code blocks. Instead of Pygments.rb, it’s now Rouge. If you were using the highlight tag with certain options, such as hl_lines, they may not be available when using Rouge. To go back to using Pygments, set highlighter: pygments in your _config.yml file and run gem install pygments.rb or add gem 'pygments.rb' to your project’s Gemfile.

Relative Permalink support removed

In Jekyll 3 and above, relative permalinks have been deprecated. If you created your site using Jekyll 2 and below, you may receive the following error when trying to serve or build:

Since v3.0, permalinks for pages in subfolders must be relative to the site
source directory, not the parent directory. Check
http://jekyllrb.com/docs/upgrading/ for more info.

This can be fixed by removing the following line from your _config.yml file:

relative_permalinks: true

Did we miss something? Please click “Improve this page” above and add a section. Thanks!

Back

Next