Hugo

A bit over a year ago I decided to set up my own personal website. I ended up purchasing licence for Statamic and running my site in Azure. I wrote then: There are lots of small things to improve, but I feel that I now have a solid base that should not need much maintenance for quite some time.

But the reality was that new versions of Statamic kept coming and I started to feel stressed about not keeping up with the updates. I was afraid that at some point I would be so far behind in the updates that keeping my site running would require major rework. Then came the news about version 2 of Statamic and major increase in the license costs. I felt that something needed to be done.

Grav

I started to look alternative products in the flat file CMS landscape and came across Grav. It is rather similar to Statamic, but open source. It also seems to have quite a good momentum going on so I decided to give it a try. It took about a day for me to get my site running on top of Grav with exactly same functionality and looks. Not bad, but the situation still remained: It seemed that the CMS running my blog got more updates than the blog itself. I wanted something simpler.

Summer came and I didn’t give too much thought for the site upgrade until I saw this tweet from Maarten Balliauw:

So what are the cool kids using these days to power their blog? Want to move away from DotNetBlogEngine into something very lightweight.
— Maarten Balliauw (@maartenballiauw) July 28, 2016

The discussion that started was exactly what I needed. Lots of different options were proposed, some I knew already, but there were alse new tools that I wasn’t aware of. One name popped up multiple times: Hugo. What is Hugo?

Hugo is a general-purpose website framework. Technically speaking, Hugo is a static site generator. Unlike other systems which dynamically build a page every time a visitor requests one, Hugo does the building when you create your content. Since websites are viewed far more often than they are edited, Hugo is optimized for website viewing while providing a great writing experience.

Instead of running a full fledged CMS that I needed to keep updating, I could just use a static site generator to turn my content into static HTML files. I could still use simple markdown files to create content, but before uploading to my server those would be converted to static HTML. This sounded something worth trying.

Rebuild for minimalism

First I decided to convert my site to exact copy of the existing one. And there probably wouldn’t have been any issues doing just that. But again I wanted something simpler. If the engine of my site was going to be simple, then my site should be too. Browsing through the theme showcase that Hugo provides, I found myself looking at the ones that were build on top of a simple css framework, Skeleton.css. Skeleton provides responsive grid-system and styles for basic HTML elements, all in less than 400 lines of css. No javascript needed.

I then tried to find some real life examples of sites build on top of Hugo and Skeleton and bumped into Mario Sanchez Carrion’s website. He has his entire website code published in Github and he has also created repository of an example site with minimal Hugo setup. I must admit that I liked his site and started to build mine based on his work.

After getting handle of Hugo’s internal logic, it was quite easy to get all the bits and pieces in place in my local environment. At the same time I reorganized the stucture of my blog so that I have separate section for the tech stuff. I didn’t want to lose the possible google hits of my earlier work, so I needed to add redirect rules for the posts. Luckily that was really easy with Hugo and required just one more line in the frontmatter of the post for the alias. Following line in the frontmatter will redirect all calls to the earlier adrress under “blog” to the new address that currently is under “technology”:

aliases: [/blog/statamic-in-azure-with-custom-deployment-and-gulp]

If posts are shared to social media, proper Open Graph metadata is essential. With statamic I had a setup where metadata tags were parsed form post frontmatter and I decided to figure out similar mechanism with Hugo. It ended up being very easy. Adding following tags to my header layout tries to fetch metadata contents from post frontmatter and falls back to default values if post specific values can’t be found:

Since I dropped dedicated navigation from my site, I ended up with no need for any javascript libraries at all (except for the GA script). The previous version of my site was already rather simple, but now I have taken that one level up. Focus is on content that works well on desktop and mobile, no bells and whistles at all.

I can throw my site to practically any webserver or even host it from my dropbox account. No requirements for PHP, databases or additional external libraries. Running Hugo locally using built-in webserver is also a breeze: just keep editing and your browser updates automaticly. Simple, very simple.

Deploying to Azure

I had the Statamic version of my site running in Azure and I didn’t want to re-configure my DNS so the goal was to be able to deploy Hugo site to the same Web App that I used for Statamic. I also wanted the publishing process to be as simple as possible and independent of my local setup. That means running the conversion to static content during the deployment. There are few of benefits from doing it like this:

I can edit my markdown files using any device and publish new content as long as I’m able to push it to my git repository. Web UI of my repo host (Bitbucket) works fine.
I only need the source data in my repository, static HTML is generated on the fly during deployment.
I don’t need to upload the source content to my webserver, only static HTML is copied over during deployment.

On the other hand I need to have the Hugo binary within my git repository. At least I’m not aware of any other way to run Hugo during the deployment process. Changes to my KUDU deployment script look like this:

As you can see the Hugo deployment has two phases: first one does the conversion to static HTML format and the second one copies only the result to the webserver.

Summary

There are numerous different static site generators available in the internet and Hugo is just one of them. For me, Hugo made it very simple to move from CMS-based website to staticly generated one. I could easily move my content (having it in markdown format to begin with obviously helped) and get old urls redirected so that I won’t lose any search engine hits. I could get my deployment process to work as smoothly as I possibly could hope for.

One really interesting new product in .NET landscape is Wyam. It’s open source and build on top of new .NET Core stack so it is just about as fresh as it can get from the tech point of view. Scott Hanselman wrote a post about Wyam just few weeks back. I recommend reading that if you are interested in a static site generator build on using .NET Core.

One thing that I’m missing in my website is possiblity to add comments. I know that there are 3rd party tools like Disqus, but I would like to have something more in line with the static nature of the site. Some people have solved the issue with adding comments as pull requests to the code repository, but in my case that would be really heavy. So the search for optimal commenting solution continues.