Why migrate?

For a few years, this very blog was managed and hosted by WordPress. It served me well but my WordPress instance was beginning to be hard to maintain.

  • I was stuck with PHP 5 which is not supported by WordPress anymore.
  • Some of my plugins did not transition to PHP 7 (more on this later).
  • I wanted to get rid of the ‘/blog/’ subfolder where the pages were served from, but it is not so easy: it requires to reconfigure the site and modify the database.

After some research I found that it would not be too difficult to migrate the blog to Jekyll. And that the advantages it brings to the table would be worth it.

What is Jekyll anyway?

Jekyll is not a CMS like WordPress: you cannot edit your articles online, nor can you give access to many writers. Instead, it is a static site generator.

It works a bit like a compiler: feed it with some source files (post, configuration, templates, etc.) and it will generate the files forming the whole website with its build command. All you have to do then is to copy it in some folder served by your webserver, and voilà!

Advantages of Jekyll over WordPress

Most of the advantages of Jekyll are due to its very nature as a static website generator:

  • The “source” of my blog can now be easily versioned by git
  • Server-side, the only dependency is a webserver. So it is very easy to host and to move.
  • The performance is dramatically improved. My blog is hosted on a cheap/slow server and it showed.
  • The attack surface is very now very small. There is no more code executed on the server, no database. And the WordPress plugins that did not support PHP7 were a bit scary 😅.

Jekyll itself is a Ruby application and accepts plugins that are also written in Ruby. All is managed using RubyGem, the packet manager, so it is really easy to keep track of all the versions. If in a few years I want to rebuild my blog using the exact same software that I used today it will be possible 😀.

Plugin declaration in the site’s configuration file:

plugins:
  - jekyll-feed
  - jekyll-seo-tag
  - jekyll-paginate
  - jekyll-spaceship
  - jekyll-postfiles

Plugin declaration for RubyGem ; versions can be specified:

# Theme
gem "jekyll-theme-yat", "~> 1.6.4"
# If you have any plugins, put them here!
group :jekyll_plugins do
  gem "jekyll-feed", "~> 0.12"
  gem "jekyll-paginate"
  gem "jekyll-spaceship"  # read doc on github
  gem "jekyll-postfiles"  # to easy image management: https://github.com/nhoizey/jekyll-postfiles
  gem "jekyll-seo-tag"    # generates metadata for SEO: https://github.com/jekyll/jekyll-seo-tag
end

There is one disadvantage though.

As by nature my blog is now static, there is no native way to handle comments. So now I host them on Disqus.

How to migrate

It is less painful that we could imagine.

Posts and configuration

The first step is of course to export the posts from WordPress. Luckily, this is the purpose of a WordPress plugin: Jekyll Exporter. After a few clicks, you download a zip containing the following folders and files:

  • _posts/
    All your posts in the Markdown format. Html being valid inside Markdown documents, some delicate layout stay in html so nothing is lost by the conversion to the new format.

  • wp-content/
    All the media files that were uploaded to WordPress. The posts point to this folder so it can be left as-is without any modification.

  • _config.yml/
    The website configuration that is derived as much as possible from its options in WordPress.

From there it is necessary to review the post files, as enhancements are still possible. My blog is quite modest in size, so this process did not take many time.

Jekyll offers to serve the website, so it can be live previewed on the localhost, or to build it so it can be sent to the webserver.

The default theme provided by Jekyll, Minima, is nice but a bit too spartan for my taste.



A more elaborated theme is welcomed. I chose YAT, which is elegant and comes with some of the most useful plugins. I also added some plugins to help with pagination and content management, and here we are!

All the migration was done in just a few hours!

Comments

For the comments, I migrated to Disqus. Once again, the process is painless.

Install the WordPress Disqus plugin and activate it. This automatically imports all the comments into Disqus servers.

Jekyll-side, there is also a Disqus plugin that opportunely comes along YAT. All is left to do is to activate it and enter the credentials. Jekyll will then embed all the necessary JavaScript files into the html when it will build the site.

Modernizing the server

I also took the opportunity to modernize my server-side software. Although this was of course not mandatory, my new blog does not need much, so it was tempting as there was not much to upgrade.

I decided to go with Docker containers. Traefik routes the http requests between my two domains, each one served by an independent instance of Nginx. As they are dedicated to a single domain, the Nginx configurations files are focused and easy to read. Nginx handles the permanent 301 redirections from my old post URLs to the new ones, while Traefik performs some preprocessings on the HTTP requests and forces a secured TLS connection.

If I ever want to move my blog to another provider, all I have to do is copy the static files and restart the Docker containers. It is only a matter of minutes 😎.