Migrating my blog to hugo and S3

I recently replaced my tumblr-hosted blog with a static one generated by hugo. Even though it was my first attempt, I was able to grasp how it works and generate the minimal skeleton in a couple of hours. After that, transforming my current posts in files compatible with hugo turned to be trivial as it was to maintain a site map that was consistent between the old and new instances.

As always, the look and feel took most of the effort. Not because it was technically difficult but because there were plenty of options available, more than ninety themes ready to use and adapt. Once I chose one, changing it to suit my needs was not extremely complex.

Migrating the content

I already had the source of my posts in Markdown, since tumblr supports it. To make it available to hugo, I just needed to:

  1. Copy the file to the posts directory
  2. Add a front matter to the file similar to the one below
draft = false
date = "2016-01-07"
tags = ["scheme"]
type = "post"
title = "..."
aliases = ["/post/..../the-title"]

This is the post text

The fact of copying the file to the content/post directory tells hugo that it is a post or, more precisely, its archetype is post. Hugo is able to manage different document types and the archetype plays a key role on this by defining which fields the document should have in the front matter. These fields can be used by hugo and the template engine to determine if a post is shown or what information it will display.

The mapping between an archetype and the fields in the front matter is part of both hugo and the theme configuration options. Once we have an archetype in place, the generator can help us to create new documents with example fields in its front matter:

hugo new post/another-post.md

Fortunately, for those not wanting to get themselves too much into hugo, the default settings work as expected and the themes I tested did not have too many requirements on specific front matter fields. Therefore, I was able to just copy my Markdown files to the content directory and manually add the the required fields. A matter of minutes.

The octopress users have probably recognized the alias field in the example above. It enables us to define an alternate URL to access a document and came in handy to preserve the old URL of my posts while in tumblr. By defining the former URL as an alias of the new one, I was able to ensure that once the DNS changed, external sites pointing to the old URLs would not need to be updated. As a side effect, for those worried about these matters, the positioning in search engines should be less affected by the migration.

The source code

Another point where tumblr was not extremely good, in my humble opinion, was in posting source code snippets. I relied on github gists but I did not like the fact of having my content spread between two places. Also, it made the posting process more complex than I expected.

Hugo is more powerful in this specific area. Nothing surprising since these kinds of tools are normally focused towards deeply technical sites but, in any case, a welcome feature. It can be configured to use pygments to generate a colorful HTML or the ubiquitous highlight.js to leave this job to the browser. I tried both and found the latter more satisfying to my particular needs.


The template engine hugo uses, based on go’s html/template, makes it easier to overcome some of the Markdown limitations when needing to lay out content beyond its somewhat scarce capabilities. Shortcodes, the feature enabling this, work in a similar way to custom tags in other templating frameworks:

{{< figure src="main.png" caption="Main" >}}

Publishing it to S3

To host an static site, it is difficult to find something more flexible and convenient than an AWS S3 or Google Cloud Storage buckets. There is plenty of documentation around but good starting points are probably this for AWS and this for GCP. Also, I found a comprehensive tutorial on how to properly enable AWS CloudFront. As a downside, using these platforms implies a recurring cost and it is advisable to implement budget control measures from day one.

I ended up using AWS S3 since is a product I am familiar with but I definitely want to explore further options. SSL support is one of the points I want to dig into, being a more advanced approach to cost control another important one.


Migrating from tumblr to a hugo-managed, static website has been a liberating experience. At the price of some additional complexity, I have now capabilities that were not available in the popular micro-blogging platform. Also, my workflow better suits my tastes, more prone to Emacs or vi than to rich text fields in web forms, and the number of tools which support it are huge.

As a disadvantage, there is an additional line in my monthly cloud services bill that I need to carefully control. This and the SSL support are going to be my focus for the little spare time I can dedicate to this blog. I will publish my findings as soon as I learn about the potential solutions. Stay tuned.