Of course I always wanted to test the fastest static website generator 😉.

But things with middleman were good. I only migrated from Middleman to Hugo because I am planning to better document one API. The current API is using OpenApi Specification, but I feel like we can add more content.

When I migrated from Jekyll to Middleman I had these changes:

100 changed files with 519 additions and 346 deletions

This migration:

Showing 393 changed files with 3,357 additions and 6,192 deletions

Good things

First the good things, of course 😊.

(1) Starting with its speed. It is not fast. It is instantaneous!!!

(2) Hugo injects code for hot-reloading. It is the best thing since sliced bread 🎉.

(3) Later on I found about shortcodes to make the md files DRYer.

I have in a lot of blog posts with something like:

* * *
<abbr title="too long; didn't read">tl;dr</abbr>

Summary of this post here with code.
* * *

I have to copy and paste that whole thing (except the content, of course), over and over again. If I switch theme and have to change the css or something I will be in trouble, besides I never put much effort in making that thing “beautful” because I would have to copy over and over.

Now I don't have that problem anymore.

I am using shortcodes! Just create a partial in layouts/shortcodes/tldr.html (tldr can be any name):

<abbr title="too long; didn't read">tl;dr</abbr>

{{ printf "%s" .Inner | markdownify }}

And call using markdown like this:

{{< tldr  >}}
Summary of this post here with code.
{{< /tldr >}}

It is amazing!

(4) Even though I had trouble with the translations, it is better to follow Hugo's default. It just works.

(5) Linking posts is different, I am still not sure if I like it or not:

Click here to go to [other post]({{< ref "posts/other-post" >}}).


(1) First, I had to fix all tags. In middleman (and I suppose Jekyll) there is no problem with this syntax:

tags: something, something2

But with hugo it has to be like this:

  - something
  - something2

After that I found issues with locale and translations.

All my blog posts follow this pattern for name of files:


And the lang metadata within the post header:

lang: pt-br
title: "Something"

(2) That lang metadata is useless. I had to remove it all and rename the files in this pattern:


Good thing for me hugo does not care about the date in the filename so I could keep it this pattern: content/posts/2019-01-01-slug.pt-br.md.

(3) The translation was other thing that bothered me. In Middleman I did my “own translation” I had a file data/translations.yml with all the translations like this:

- como-importar-imdb-usando-csvkit: "pt-br"
  how-to-import-imdb-database-using-csvkit: "en"

And I wrote my own code to link them together.

But hugo detects the translation based on filename, for that example to work I had to rename the files like:


(4) And because of that I had other issue with the URLs:

If you just create a filename content/posts/2019-01-01-something.en.md the URL will be http://localhost:1313/something/ and a filename content/posts/2019-01-01-coisa.pt-br.md will be http://localhost:1313/pt-br/coisa/.

I don't have any blog post with a language prefix, because the URL is already a translation. There will never be a conflict.

There would be too much pain to create a redirect file. And what if I move out from Netlify? I would have to follow the other server configuration to redirect. That is too much, it is easier for me to set the URL for each post:

title: "Something"
date: "2006-09-01T04:47:00-03:00"
url: "/something"
  - unix

I don't have to do that for the English blog posts but if I am going to follow a pattern it is better to apply in all blog posts.

(5) Title did not accept emojis 😐. I have to use something like {{ .Title | emojify }}.

I had other issues with:

  • (6) Sitemap
  • (7) Atom
  • (8) Useless translation of Sitemap, Atom, or robots.txt

But those require more code to explain. Maybe there will be a blog post for each one 😊.

I found this awesome hugo. It was really helpful!