75 lines
3.2 KiB
Markdown
75 lines
3.2 KiB
Markdown
---
|
||
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!_
|