Static blog generated by Hugo hosted on Google Firebase

I have migrated my blog from WordPress to static website generated by Hugo. Here is why.


Once you have learned the basics of how to use Hugo below, do check out a follow up tutorial, Hugo Static Site Generator with CI Deployment using GitLab.


WordPress is a very good content management system especially for blogs. It was running fine on my Raspberry Pi 2.

I was reading about how others were turning their website from dynamic to static and weighing the pros and cons. What better ways to experience this than to try it myself and so I did. There has been lack of updates on my blog; about 3 weeks since my previous post as I was learning more on this and working on the migration of posts.

Static vs Dynamic

The last time I built and deployed a static website was during the heydays of GeoCities. I am not going to bore you with my history here so I will stop at that.

Perhaps, one of the key reasons people wanted dynamic websites was the ease of managing content; i.e. reduce duplication, changing at one template page so that it gets reflected everywhere, etc.

That benefit is undeniably useful. However, I wanted to know if I could have the said benefits yet have them fully static without fiddling with static caching. I made a quick search for static website generator on Google and found tons of solutions that I could try. I chose Hugo because I read that it is one of the fastest static website generator.

Having a static website means:

  • Less worries of attacks on server since there is no dynamic content, i.e. SQL injection is not possible, there is no database!
  • Wide variety of free hosting options with custom domain support; i.e. GitHub and Google Firebase, just to name a few.
  • Cheap hosting options aplenty; i.e. Amazon S3 with CloudFront.

Using Hugo

Getting started

I will not be describing how to get started on Hugo. I can however point to the official Quickstart which helped me a lot. There were challenges of course and sharing them along with recommendations below.

Choosing a theme

There are lots of themes to choose from but expect the need to customise them. This requires knowledge on HTML and more importantly CSS.

Creating posts

When creating posts and naming your files on disk, I recommend naming them in the following pattern: yyyy-MM-dd-slug.
For example: This allows ordering of files by filename.
In case you were wondering what md file extension means, it is Markdown.
You will have to learn this but you will very likely find it simple once you get the hang of it.

Why does Markdown not have a syntax for doing this or that?

Markdown does not let you have the full flexibility of HTML but it is simpler. One matter that really annoyed me was not allowing custom attributes to be added into image <img> tags. I needed this because I wanted to put Lightbox2.

To overcome this limitation, I wrote a custom shortcode for Hugo.

Create a new file /layouts/shortcodes/img.html with the following body:

<p><a href="{{ .Get "src" }}" data-lightbox="{{ .Get "src" }}">
<img src="{{ .Get "src" }}" {{ if or (.Get "alt") (.Get "caption") }}alt="{{ with .Get "alt"}}{{.}}{{else}}{{ .Get "caption" }}{{ end }}"{{ end }} />

To use it, you have to replace the usual Markdown style image insertion:



{{< img src="source" alt="caption" >}}

Hugo will parse that into:

<p><a href="source" data-lightbox="source"><img src="source" alt="caption"></a></p>

Choosing a hosting provider

Considering there are very good static host providers that are free or very cheap, it was time to repurpose my Raspberry Pi 2 for other needs.

I narrowed down my options to two; GitHub Pages and Google Firebase. Both support use of custom domain name with no charge.

Reasons to choose GitHub:

  1. Valid SSL is provided but only for subdomain.
  2. Uses Fastly CDN.
  3. Soft limit bandwidth of 100GB per month compared to Firebase at 10GB.

Reasons to choose Firebase:

  1. Valid SSL is provided for custom domain free of charge.
  2. Hosted content is propagated all over the world via Google’s super fast CDN.
  3. HTTP Cache-Control header can be customised by file name pattern; i.e. images are cached for 1 year while HTML content can be given a short expiry.

Version control

With Firebase, if you made a deployment but regretted doing for whatever reasons, you could easily rollback to any of the previous versions via Firebase Console.

I highly recommend adding your website Markdown content into source control. For this, I have pushed mine into a private Git repository hosted on Google Cloud Source Repositories.