Guideline for Upgrading Jekyll from 2.x to 3.x
Note: This guideline is not suitable for default engine of GitHub (Jekyll). Because it doesn't allow to install any plugin. On the other hand, we can't use Jekyll 2 plugin. It must uses in Jekyll 3 way.
If you are a Jekyll user. You may be heard some news about announcement Jekyll 3. Then, GitHub announced to use the Jekyll 3. So, there are many changes for Jekyll 3. It describes in the Jekyll Official page.
- This article doesn't directly use to upgrade your Jekyll site, but it has some useful guidelines for upgrading by yourself.
- This article is following my site upgrading. You can see all changes in my commits (1, 2, 3, 4).
Here is some instructions
If you uses relative permalinks. It looks like
config.yml. Delete it!. Because it was removed from Jekyll 3.
Some default plugins of Jekyll 2 (dependencies) are removed out on Jekyll 3. If you want use them. You just add import some Jekyll 2 plugins manually. I used my Jekyll site as a case study.
gemsand following a list of plugin name what you want in yaml format.
gems: [jekyll-paginate, jekyll-gist, redcarpet]
You can find more removed plugin lists of jekyll 2.x below:
- jekyll-paginate – Jekyll's pagination solution from days past
- jekyll-coffeescript – processing of CoffeeScript
- jekyll-gist – the
- pygments.rb – the Pygments highlighter
- redcarpet – the Markdown processor
- toml – an alternative to YAML for configuration files
- classifier-reborn – for
From Jekyll site
Jekyll 3 has been changed syntax highlighter to kramdown.
redcarpet in my site because of I don't want to change any markdown files to support
In Jekyll 3, It doesn't automatically add a trailing slash (
/) of permalink (URL).
If you have custom permalink pages or posts, you should fix all of custom permalink posts and pages. By adding a slash (
/) at the end of your custom permalinks. (You can see my changes) For example:
permalink: notes/vimchange to
And, you should fix a custom permalink in
_config.ymltoo. You can see in my changes.
permalink: /:categories/:titlechange to
Here is a part of
_config.yml which is changed in Jekyll 3.
markdown: redcarpet gems: [jekyll-paginate, jekyll-gist, redcarpet] permalink: /:categories/:title/
Thanks for reading. If you have some questions or suggestions, please comment below.
- "Upgrading from 2.x to 3.x" by Official jekyll site