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

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:

{% highlight bash %}
$ gem update jekyll
{% endhighlight %}

<div class="note feature">
  <h5 markdown="1">Diving in</h5>
  <p markdown="1">Want to get a new Jekyll site up and running quickly? Simply
   run <code>jekyll new SITENAME</code> to create a new folder with a bare bones
   Jekyll site.</p>
</div>

### 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 `{% raw %}{{ layout.class }}{% endraw %}`.

### 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](https://github.com/tmm1/pygments.rb),
it's now [Rouge](http://rouge.jneen.net/). 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`.

_Did we miss something? Please click "Improve this page" above and add a section. Thanks!_