Thada W.
Talks

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.

Notices

  • 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 -relative_permalinks: true in 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.

    Add gems and 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 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

    From Jekyll site

  • Jekyll 3 has been changed syntax highlighter to kramdown.

I'm using redcarpet in my site because of I don't want to change any markdown files to support kramdown.

  • 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/vim change to permalink: notes/vim/

    • And, you should fix a custom permalink in _config.yml too. You can see in my changes.

      permalink: /:categories/:title change to permalink: /:categories/:title/

Lastly

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.

Bye.

Read more