In A Break I mentioned that I had tinkered with Octopress 2 & 3, experimenting with the idea of converting my blog from WordPress to Octopress. I also stated that I abandoned the idea after a few days, favouring WordPress as more practical on the whole.

But ever since Dockerising ALL THE THINGS I’d been wanting to give it another go. The thing that prompted me to reconsider was that in doing that Dockerisation I had to scale up my web VPS from a 1GB Linode to a 2GB Linode¹, adding an extra $10 to the amount I spend on servers per month.

So, having finished what turned out to be basically 6 months of work on Liquidity, I gave it another go. Hence this post.

Fairly early on in the conversion I realised that I actually didn’t need or want Octopress, and that Jekyll alone is sufficient. I’m using jekyll-docker both for local previews and for building the site that gets copied into an Nginx Docker image for deployment.

A summary of the key benefits for me of using Jekyll, relative to WordPress:

• Security:

  • Eliminating the WordPress authoring process and admin area means one less username and password for me to guard and maintain.

  • The static Nginx containers I build for deployment are surely more secure than running WordPress due to reduced attack surface.

• Authoring & Editing:

  • Over the last couple of years I’ve started using Git for more and more things (beyond just software sources). Using it to manage my blog posts is definitely preferable to WordPress’s post revision system, which I never really used. With my posts in Git I can re-use existing know-how.

  • Markdown. With WordPress I found I alternated between using the WYSIWYG editor and the HTML editor, which lead to some inconsistencies in the way I expressed things. I prefer having a single canonical authoring mode.

  • Jekyll’s minimalism should help me to focus on content above all else. That certainly has been my experience so far.

• Efficiency:

  • Eliminating the need for a MySQL container reduced the memory required on my web VPS by enough to allow me to revert it to a 1GB Linode, saving $10/month.

  • Pages might load faster for people, but this wasn’t really a major consideration. Performance under high load is another theoretical advantage but in practice it’s not a major consideration.

The Conversion

I used exitwp to get the process started, along with copying the WordPress install’s wp-content/uploads directory as assets into the Jekyll root of the Git repo that now contains all of the blog source².

Then I made a series of commits (some automated, some manual) to correct and improve the Markdown sources that exitwp generated.

In my early years using WordPress I was quite liberal with my use of 3rd party plugins and with embedding content from other locations (most notably Google Maps views of cycling routes recorded with My Tracks).

Although I made an effort in the later years to stop and counter the practice³, and although exitwp was a very helpful start, I still had to do a fair amount of work on the generated Markdown.

Key issues that I had to resolve were:

• What to do with posts that had embedded OpenStreetMap views of KML files via the WP GPX Maps plugin.

  – I didn’t want to lose the maps. There were two ways I might have kept them: using a Jekyll plugin (if I could find one), or by straight-up embedded HTML (+JavaScript). I did spend some time investigating both options, but didn’t manage to develop anything workable within the time that I was willing to spend.

  So instead I just converted them all to links to the KML files.

  It was at least simple enough to automate (and that’s just as well given the number of them). The loss isn’t so bad, because it’s only older posts that are affected – of which the majority are quite samey⁴ – and the route data itself is still there anyway, just not in such a conveniently viewable form.

• What to do with posts that used WordPress’s built in gallery support.

  – There weren’t that many, so I estimated that it would be quicker to manually expand gallery tags into explicit image references than automating it and thus went ahead with manual expansion.

  I’m quite happy having done this, as most of the posts that previously had WordPress galleries – showing small thumbnails of each image – now look better for each image being larger.

Some of the more trivial changes that I made to the generated Markdown sources follow. I automated most of them using find to exec sed:

• Repointing references to wp-content/uploads to assets.
• Parametrising all links via the site.url and site.baseurl variables.
• Removing the multiple thumbnail etc. images that were generated and stored by WordPress and replacing them with just a single scaled version of each image, generated with ImageMagick’s convert tool.
• Removing the author, comments, slug and wordpress_id properties from the exitwp generated front matter of each post.
• Replacing hyphens with en-dashes as appropriate (not really necessary as part of the conversion, since it was just that I had been using hyphens incorrectly until now, but the conversion was an opportunity for minor improvement too).
• Changing the categories listed in the generated front matter of each post to be tags⁵ in order that Jekyll’s built-in ‘pretty’ permalink style gives the same results as what I had set WordPress up to generate.
• Moving assets so that each post has its own assets directory. Again, not required as part of the conversion, but this was an opportunity to make things more maintainable.
• Fixing incorrectly generated Markdown. This included but was not limited to:
  1. Manually escaping asterisks that required it.
  2. Manually converting hyphens that required it to en-dashes (encoded as double hyphens).
  3. Converting literally encoded en-dashes to double hyphens.
  4. Manually correcting nested list content indentation and removing redundant newlines.
  5. Converting tables to Markdown form.
  6. Adjusting header types.
  7. Re-adding dropped superscript tags, converting a footnote header to a horizontal rule.
  8. Replacing QR codes/links that pointed to the Android Market with Google Play badges/links.
  9. Adding back lost line breaks identified during review by adding terminal double spaces.
• Changing the index to group posts by month (as described at http://stackoverflow.com/questions/19086284/jekyll-liquid-templating-how-to-group-blog-posts-by-year/20777475#20777475).
• Fixing broken & redirecting links (identified using http://www.ryanalynporter.com/2012/10/06/introducing-the-link-checker-ruby-gem/) and switching some from HTTP to HTTPS (where now supported).

1. That was because in doing the Dockerisation I had elected to make maple.dhpiggott.net’s Piwik install and piggott.me.uk’s WordPress install have their own MySQL containers. I could have made them share one and would probably have then been able to stick with the 1GB Linode, but having them isolated was just a much more maintainable and practical setup.
2. Prior to the conversion it only contained the configuration and machinery used for deploying and maintaining the WordPress install, but not the actual WordPress data itself.
3. Most notably by exporting the My Tracks routes and spreadsheets from Google, hosting my own copies as WordPress uploads, and editing posts that had embedded Google Maps views of the routes so they were instead displayed using the WP GPX Maps plugin to render views of the KML route files.
4. The majority of posts from 2009 to 2011 are records of individual bike rides. On the one hand, it wasn’t a bad habit to be in, as it can’t have been bad for my motivation, but on the other, it hardly makes for interesting reading. Recognising that, I started in 2012 to periodically log multiple rides in a single post. In 2013 I stopped using My Tracks and switched to Endomondo, which I continue to use today. It logs more than enough in the way of data for me, and my blog is now hopefully less samey.
5. I’m not showing categories anywhere now, but have changed them to tags rather than deleting them because that could change.