The complete guide on how to update your Jekyll blog to the latest version on your Windows machine

I lately had to install Jekyll on my new machine for some local development and realized that I should also update the Jekyll version of my blog. With this guide I am going to show you the steps for updating your Jekyll blog and how to fix a number of possible errors, if your blog or its dependencies are outdated.

Install the latest version of Jekyll on your Windows machine

Follow the steps described in the Jekyll documentation. No surprises should arise in the step.

Update the .gitignore file of your blog

Add the following .jekyll-cache if not already in the file. This will prohibit git from committing temporary Jekyll files.

Create a new Gemfile or continue using the _config.yml

If your blog depends on an older version of Jekyll (check the package.json file) then on the root folder you will see a _config.yml file but not a Gemfile. If that is the case, you have two options:

• Create a new blog with in another folder with jekyll new myblog and copy the Gemfile from this blog to your blog. You will then have to add the gems array from _config.yml to the Gemfile under this area:

  group :jekyll_plugins do
  gem "jekyll-feed", "~> 0.12"
  # Add the plugins of your blog here
  end
  

  After that you will work with the bundle install command to install all the plugins defined in the Gemfile. For more information on Gemfile check the Jekyll documentation.

• The second option is to not create any Gemfile, but to slightly update the _config.yml file. Rename the gems properties into plugins.

Fix any errors or warnings when you run the jekyll serve command

• One possible warning could be the following Deprecation: You appear to have pagination turned on, but you haven't included the 'jekyll-paginate' gem. Ensure you have 'plugins: [jekyll-paginate]' in your configuration file.. We already fixed that by renaming the gems area of _config.yml into plugins.

• Liquid Warning: Liquid syntax error (line XX): Expected id but found open_square in "{{ page.[1] }}" in XXX. To fix this warning (which might appear multiple times, based on the number of your posts) simple remove the dot between the array and the index ({{ page[1] }} instead of {{ page.[1] }}) in the file pointed out.

Errors fixes when hosting your blog on GitHub Pages

• GitHub Pages do not allow custom ruby gems. If you try to use one, you get a build error that looks like this one: The tag 'relevant_posts_list' on line 45 in '/_layouts/post.html' is not a recognized Liquid tag. You will either have to use a standard Jekyll gem with similar functionality to your gem or build locally, commit and push you Jekyll blog. This is what stated in the GitHub Pages documentation: GitHub Pages cannot build sites using unsupported plugins. If you want to use unsupported plugins, generate your site locally and then push your site’s static files to GitHub.

• Another general error message of GitHub can be the following: Page build failed. For more information, see https://docs.github.com/github/working-with-github-pages/troubleshooting-jekyll-build-errors-for-github-pages-sites#troubleshooting-build-errors.. I advise you to build the blog locally with the jekyll serve command. This will log the errors so you can fix them. Most of the time the error will have to do with invalid markdown code.