From Middleman to Hugo
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:
This migration:
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" >}}).
Issues
(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:
tags:
- something
- something2
After that I found issues with locale and translations.
All my blog posts follow this pattern for name of files:
content/posts/2019-01-01-slug.md
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:
content/posts/slug.pt-br.md
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:
content/posts/2019-01-01-how-to-import-imdb-database-using-csvkit.pt-br.md
content/posts/2019-01-01-how-to-import-imdb-database-using-csvkit.en.md
(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"
tags:
- 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!