Migrating De Programmatica Ipsum From WordPress to Hugo

I finally did it: I migrated my monthly magazine “De Programmatica Ipsum” from WordPress to Hugo, and this blog post explains how it happened.

Graham and I started De Programmatica Ipsum (henceforth referred to as “DPI”) in October 2018 as a WordPress website. It was the quickest and easiest way to get a website up and running, and to build our idea from scratch. Click, click, click, done.

WordPress is great, and it has served DPI well, but it’s also bloated, and it can get very slow depending on your combination of plugins. Some themes can also slow it down considerably; of course, adding a plugin such as WP Super Cache helps a lot, but again, it’s a lot of infrastructure for not much at the end.

In particular, using WordPress for DPI proved to be overkill: the website mostly features text content, and has no comments or other dynamic features except for the search engine. Using Hugo, the content management system I’m using for the website that you are reading precisely now, was a natural objective, and has been for years. So, this week I took things in hand and made it happen.

The end result looks very nice, I think! Maybe the fact that this month’s issue is about Design gave me some inspiration?

Migration Process

Of course, I’ve done this in the past for the blog you’re reading, so I’ll just expand on some specifics. Roughly speaking, this is what I had to do:

1. I exported the contents of the WordPress website using the WordPress to Jekyll Exporter plugin by Ben Balter. This is a very simple plugin without settings or anything; just install, click a button, and download a ZIP file.
   • OK, in my case I had to ssh into the server and execute the command line script because of timeouts, but it worked in the end.
2. I created a new Hugo website, and imported all the Markdown and image files generated by the plugin in the previous step.
3. Dived into the Hugo Themes catalog for a while until I found a suitable theme, called “Ed”, which I found beautiful yet functional, and perfect for DPI.
4. Selected some nice fonts via a thorough casting on Google Fonts: EB Garamond as the main text font, Cabin as its sans-serif counterpart, and JetBrains Mono in the role of the monospaced font.
5. Bundled the font files and generated the required CSS for self-hosting with the GNOME Webfont Kit Generator application (available on Flatpak as com.rafaelmardojai.WebfontKitGenerator for the curious among you).
6. Edited the content of the Markdown files in depth, adding a new taxonomy called “Issues” and reassigning categories and stuff.
7. Tweaked the CSS and Hugo templates a lot. Those who make a living styling websites know what I mean.
   • As a side note, it’s noteworthy to indicate that while I love Hugo, the documentation (and in particular, the Hugo template functions documentation) is downright bad.
8. Added the required infrastructure to generate a search engine index. This works both locally (using a set of make commands) and also remotely (on the CI/CD pipeline on GitLab).
9. Pushed everything into a private Git repository on GitLab.
10. Added a suitable .gitlab-ci.yml file, and created a scheduled pipeline that executes every Monday.
11. Executed the pipeline (to my surprise, it worked on the 2nd try!) and removed the WordPress folder from the website.

The whole process took me about 2 days and a half of work. Needless to say, I reused a lot of infrastructure that I am using for this website, which of course helped me to go fast.

And yes, steps 6 and 7 were the ones that took the longest. There’s a lot of work that you can’t automate, and it requires a lot of manual tweaking. Thankfully, the Markdown exported by the plugin was of excellent quality, and it didn’t need any modifications.

Advantages

There are quite a few!

• The new DPI is fast. It should be: after all it’s just pure, minified HTML and a few images here and there. There are plenty of optimizations possible for that.
• The new search engine is even faster. Oh, and it’s compatible with OpenSearch, did you know? (just like this website, by the way!)
• I’m particularly happy about the new Archives page.
• I could keep almost all URLs intact, in particular those of the categories and the individual blog posts.
  • Some others are new, and in particular, I could not find out how to change the URL of the RSS feed. So if you’re subscribed to the RSS feed of DPI, please change your subscription and use this URL now: deprogrammaticaipsum.com/index.xml
• There are no cookies of any kind: the website only collects cookieless, GDPR-friendly analytics that are fed into a Matomo instance.
• I don’t have to deal with WordPress shenanigans anymore, such as the dreaded Gutenberg editor, and the obnoxious Jetpack stuff.
• To create new editions, I just create a pull request on GitLab, push my changes there, and when I’m ready, I merge to master and the scheduled pipeline pushes everything into production on the first Monday of each month.
  • It’s all very “GitOps” now, and literally the same workflow as the one I use for this blog.
• Hugo has a fantastic preview function (hugo server) that automatically rebuilds the website contents and updates the browser as I write. This lets me use any Markdown editor to work on future editions (in my case, my current choice is Typora).

Check out the new style of De Programmatica Ipsum and if you’re a regular reader and enjoy the website, consider contributing to its development or subscribing to our monthly newsletter.