Building a Blog With Hugo

Tuesday, July 14, 2020

In my inaugural Twitch stream, I went from an empty folder on my machine, to having a static blog site (complete with first post), with cloud hosting and automated continuous delivery in about an hour.

This post reviews some of the detail and includes useful links to the resources I used.

Why a Static Site?

Static website generators are command-line tools which take a set of text files containing your content (usually written in a simple markup language like Markdown) and, using a series of templates, generate an entire site as a series of HTML and CSS files.

I’ve worked with Umbraco for over a decade, so when it comes to building content managed websites, that’s usually my ‘go to’ platform of choice.

On this occasion, though, I was keen to try a static website. I’m likely to be the only person who will be editing the content, so there’s no need to cater for people who don’t know Markdown or Git.

I like the idea of having all of the content in version control, and the simplicity of having a website which is pure HTML, with no database behind it has a certain elegance to it.

The Tools

I chose the Hugo static site generator. It is very popular, actively maintained, feature rich and extremely fast. That said, with a site this small, speed isn’t really a consideration, but I do believe performance is a feature, so I appreciate Hugo’s speed none-the-less!

I’m no designer, and my front-end development skills aren’t exactly up there with the greats - so to kick things off, and in the spirit of not letting perfect be the enemy of good, I chose a theme from the Hugo Theme Library. I chose Notepadium for a number of reasons. I like the simple, clean look and the choice of light and dark themes. In the interests of keeping things simple, it also doesn’t rely on any JavaScript.

Finally, I used the new Azure Static Web Apps service (which is currently still in preview) to host the site. This includes direct integration with GitHub Actions to arrange the automatic build and deployment of the site on every source control commit.

The Process

Installing Hugo doesn’t take much work - simply download to a folder and (for convenience) add it to your PATH. In case you hadn’t noticed, I’m working in Windows.

Hugo’s Quick Start Guide makes light work of getting things going. Just remember to branch out to the Notepadium documentation when it comes to installing the theme.

Once the site works as it should, push the source to GitHub and follow the Azure Static Web Apps documentation to setup the automated deployment of the website.

The Magic

Whilst I was pleased to see this all working as it should - I was intrigued to see how the automated deployment process worked. After all, I just gave the Azure Portal access to the GitHub repository and it worked out how to build and deploy the site.

After a little digging, I found that the answer lies in Oryx - an open source build system developed by Microsoft. This dynamically generates build scripts by analysing a codebase’s contents.

This is used at the heart of the GitHub Action which is automatically created by the Azure Portal. So - every time a change to the source is committed, an Oryx based container is fired up. This retrieves the source, uses Hugo to build it and deploys the built artefacts to Azure.

blog

Perfect is the Enemy of Good