Today I updated my blog for the first time in the past two-three years.

One difficulty that I encountered was that Jekyll has gone through a few changes and it requires some changes to make it compatible with the latest mechanism.

What I used to do to run my blog on a local server was simply:

  $ jekyll serve

But now on the official tutorial, it recommends running:

  $ bundle exec jekyll serve

I was not sure what this bundle command does, but when I tried to run it, it threw an error:

  Could not locate Gemfile

It turns out that the bundle is looking for a gemfile which is supposed to be auto-generated by the latest jekyll but not by the old jekyll. Since my blog was created using the old jekyll, gemfile isn’t there. At this point, I could get around this problem by running

  jekyll serve

But after some digging, it seems that bundle is a better way of dependency management. jekyll serve runs the packages that are available on the server, while bundle exec uses the package versions that are specified in the Gemfile or Gemfile.lock. If Gemfile/Gemfile.lock is available, it ensures that the same code is guaranteed to work even if it’s executed on a different machine. It’s similar to the requirements.txt file in pip.

For more details about this design, here’s a tutorial: Bundler rationale

To migrate the code base to the latest jekyll (3.8.5) at the time of writing, one can simply do the following:

  1. backup your old code
  2. create a new directory by jekyll new newblog
  3. copy these files from the root directory of the new blog to the root directory of your old blog: 404.html(if you didn’t have any), Gemfile, Gemfile.lock.
  4. verify by running bundle exec jekyll serve from the root directory of the blog.

I hope that it is helpful information for someone.