How to Build This Blog

For this blog, I chose Hugo. The reason I chose Hugo is that that’s what Shay Nehmad is using. 🤷

Hugo is a static site generator, which means the site is not served by a server which runs code (like Wordpress) - instead, it’s served by a server which serves static files only. I write new posts in Markdown format, and then I use Hugo to rebuild the site.

In my experience, using Hugo is not as straightforward as using traditional blogging platforms (like Wordpress), and you do need to have some coding experience. I’ve had to learn some things about how Hugo works in order to develop this blog. I’ve even learned about Git submodules! 😁

I got started by reading Shay’s post, “How to Build This Blog”. Then, I looked at Hugo’s theme library, and chose the theme Zzo.

In Hugo, you are kind of married to the theme you choose. Once I chose Zzo, I had to set up a lot of Zzo-specific configuration. Besides reading the documentation of the theme and of Hugo itself, another trick that proved useful was to look at the templates/partials themselves (in the Zzo source code) to figure out what site element is controlled by what configuration.

In addition to configuration, I’ve had to change some behavior / fix bugs in Zzo itself. To do this, I’ve forked the Zzo repo, made the changes there, and opened a few pull requests to contribute the fixes back upstream. I’ve detailed an example below:

“Reading time” as “Shorts Size”

By default, Zzo shows the reading time like this:

☕ 5 min read

Instead of this, suppose that we want to have:

🩳 Size M

Step 1: Finding where things are

Even without knowing anything about the code, we know that the string "min read" must be referenced somewhere. Looking for it in the entire source code of the theme, we find it in the file i18n/en.toml:

1
2


[reading-time]
other = "min read"

This tells us it’d be a good idea to search for "reading-time", and indeed, we find it in 4 places:

These 4 places correspond to all four ways that the reading time may be shown: Inside a page, or in 3 different styles of page summaries.

Step 2: Fixing the theme

The code which refers to "reading-time" looks like this:

{{ .ReadingTime }} {{ i18n "reading-time" }}

We see that it is hardcoded in the template that the number appears before the string. That’s no good for us - we want the number to be a parameter for the "reading-time" string. Fortunately, Hugo can do this - and it is even a standard example in the documentation. Basically, you pass it as a parameter like this:

{{ i18n "reading-time" .ReadingTime }}

And modify the i18n string like this:

1
2


[reading-time]
other = "{{ .Count }} min read"

With this knowledge, I made the necessary changes and submitted a pull request.

By the way, while we’re looking at these partials, we can see where the ☕ emoji comes from:

{{ ($.Site.Params.readingTimeIcon | safeHTML) | default "☕" }}

This indicates we can control the emoji by changing the readingTimeIcon site configuration, which indeed appears in Zzo’s sample params.toml file.

Step 3: Defining the string

After reading some more documentation (this time it’s of Go’s template package), I was ready to define the string. To do this, I had to define my own i18n/en.toml. The way Hugo works is it evaluates the site’s files first, and at the theme’s files afterwards; so I just created this path and file in the root of my site.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


[tooltip-reading-time]
other = "Shorts Size"

[reading-time]
other = "Size \
    {{ if eq .Count 1 }} \
        XS \
    {{ else if eq .Count 2 3 }} \
        S \
    {{ else if eq .Count 4 5 6 }} \
        M \
    {{ else if eq .Count 7 8 9 10 }} \
        L \
    {{ else }} \
        XL \
    {{ end }}"

And that’s it - this finally achieves what we wanted.