From Wordpress to Hugo

I have been running this site on WordPress for the past one month. Just after the first week, I started getting doubts about the future of our relationship. It is not that WordPress lacks power or expressiveness. One could build almost any kind of site using WordPress with very little effort. What it lacks in my opinion is the simplicity that a blogger needs.

Problems with WordPress

The most annoying aspect of WordPress for me is its editor. Its interface is very basic. You have the option to enter HTML or text. You can switch back and forth between these two input choices. It works fairly well for normal posts. But when you include code listings, it goes mad. You can only enter code in the HTML window. Then if you switch back to the text view, your code might become mangled, and many symbols (e.g., the comparison operators) could get replaced with their HTML codes.

Maths

Another irritating issue is related to the input of mathematical symbols. By default, to enter inline maths you need to start the formula using $latex, and end it with a $. That is \(8\) characters, including the space required to separate the content from the markup! I am so used to achieving the same in LaTeX using \(2\) characters that writing the first blog post on a WordPress.com site (without access to any plugins) almost gave me the carpal tunnel syndrome.

For the ability to install plugins, I shifted to a Wordpress.org hosting. There is a MathJax plugin for WordPress which works well. The only problem is that even using MathJax, we cannot use the two dollar syntax for maths–we have to use \( and \) to surround maths now. That is \(4\) characters, and noting that the backward slashes and brackets are harder to type than dollars and letters, effectively, I don’t think the effort is significantly less.

Org-mode to the rescue

At this juncture, I discovered the org2blog Emacs plugin.

To the uninitiated, org is a fantastic markup language that is mostly like plain text. It supports maths with the $$ syntax. It also supports tables, lists and code listing to a phenomenal level.

When we use org2blog, we need not directly tamper with HTML anymore. We can write org files, and org2blog will take care of the conversion to HTML and the transferring of the resulting files to the WordPress server.

This setup worked fine. I loved the fact that I could do all my editing using my trusted editor. I could even include LaTeX snippets for drawing diagrams in the org file. When exporting to HTML, org would compile the snippets separately, convert the resulting PDFs to .png files, and then link those images in the HTML output. org2blog would then transfer both the HTML and the images to the server. How cool is that?

XML-RPC

Then I started getting these weird \(404\) errors when trying to update posts. The errors were weird because I could resolve the errors by editing the post and removing some particular symbols. Sometimes the symbol may be a bracket, and sometimes it may be a dash. I do not know why exactly the errors occurred. I guess it has got something to with the communication protocol (known as XML-RPC) that is used by the editor to talk to the WordPress server.

Of course, one option was to locally generate the HTML file from the org input, and then paste the HTML in the WordPress editor. But that was more work than I was willing to do. What is more, there was another issue which was bothering me.

The Plugin System

WordPress has a ton of plugins that can be directly installed (or updated) from the main interface. Unfortunately, the customization options for the plugins are often quite limited. We can always edit the source directly, but then the changes will be overridden when the plugin is updated.

Instead of trying to find workarounds to solve this issue, I decided to look for alternatives.

Static Site Generators

I found that something called Static Site Generators (SSGs) are all the rage now in web development. Static sites are those without any server side computation. Servers for static sites are mostly just file providers. In the beginning of the internet, all the sites were static sites. Then the landscape completely transformed with the advent of server-side technology which made dynamic sites possible. Why would anyone want to go back to the old age?

The reasons are speed, security, and cheap hosting. As there is no server side computation, the serving of web pages can be extremely fast. And due to the same reason, there is not much attack surface for a cracker to exploit. Also, the lesser demands on the server resources make hosting cheaper.

But maintaining the old static websites required direct editing of HTML files. This is where static site generators come in. These programs perform the task of generating HTML from an input written in simpler markup languages like org or (more popularly) markdown. If we specify a theme, the generator will use it to style the output. So visually, it may not be possible to tell the modern static sites apart.

You Own Your Site!

What I like the most about SSGs is how neatly the workflow of creating and updating the static sites links together with the developer workflow. The entire source for an SSG-generated static site can be maintained in a single directory. The best part is that this directory can be version-controlled. In fact, the hosts that support SSGs require that the directory is version-controlled using something like git. The server will update the site as and when new commits are pushed upstream.

This ensures that no matter what happens to your hosting provider, your data will be always yours. No extra steps are necessary for backing up the site.

Hugo

Currently there are dozens of static site generators available, and more are springing up every week, it seems. After reading some reviews, I chose the Hugo static site generator. It is one of the most popular static site generators at the moment.

Hugo takes in content written in the markdown format¹. It then converts the content into HTML files according to the templates specified by the site’s theme. Lots of themes are readily available over at the Hugo site.

In my case, after trying out some themes, I overreached myself and decided to write my own theme. I figured that that would help me come to grips with the ecosystem.

The Pragma theme

So I ended up creating this theme. Being a web-development newbie, it took me more than two weeks to do it. However, it was also incredibly easy in one sense as there was no scarcity of examples. All the themes given in the Hugo website are free (again, as in freedom). So whenever I wanted to do something which I could not figure out how, I could just look up the source of a theme which does something similar.

Hugo uses Go as its templating language (Go is also the language in which Hugo is written). I do not know Go, but the bits of the language necessary for writing templates were easy to pick up from the Hugo documentation.

The CSS part was another story. CSS is the part of a web-page which dictates how it should look. Things like how big the headings should be, what color should they have, should they be aligned left/right/center, etc. are all specified as CSS styles. So it is very important for a theme. Unfortunately, making CSS from scratch is hard-work. You need to specify the look of each HTML tag, and even of many of the tag combinations.

Fortunately, there are frameworks like Bootstrap and Bulma which make it easier. They define lots of handy CSS classes which we can readily use in our themes. Wanting to make the CSS files of my theme as small as possible, I initially chose a tiny framework called Milligram. After building the theme, however, I copied only the classes I used into the theme’s CSS file in order to keep the dependencies minimum.

Conclusion

I do not miss WordPress at all. It is not that Hugo is without any bugs. But Hugo, like most other SSGs, is a lean piece of software, and most of the bugs can be addressed in a straightforward manner.

More importantly, in the event that I need to switch to another server back-end in the future, the transition is most probably going to be easier, with only the theme’s template sections needing to change while the CSS portions remaining the same.

I am also happy that I took the effort to build my own theme. Sure, there are much better-looking themes out there, but I am proud of the fact that now for all of this site’s faults—from the poorly chosen fonts, colors, and layouts, to the almost illegible content itself—I, and I alone, am to blame. That gives me a warm feeling!