There are many ways to organize your content in Hugo, including custom taxonomies. But I wanted something simpler: a page that lists all the “things” I have written about, with links to the corresponding posts. Here is how I figured it out.

• Content
• Dictionary
• List
• Conclusion

Maybe not the best or most elegant way, but it works and since Hugo is a static site generator, no one will ever know! :)

“Index” is a bit confusing in the web world, but I mean it as “an alphabetical listing of items and their location”.

Content

So on the content side, we need to add this to front mater of each post:

items:
- Name of a thing
- Name of another thing
- Etc.

If there are some pesky characters like colon, the name should be enclosed in quotes:
- "Thing: Not the other thing!"

Dictionary

Then we need a list.html in layouts/map/ folder. map can be whatever we want. I won’t cover how to deal with layouts. Here is the main thing, I will go through the details after that:

{{ $mapItems := dict }}

{{ range .Site.RegularPages }}
    {{ $mapDate := .Date | time.Format "060102150405" }}
    {{ $mapLink := .Permalink }}
    {{ $mapTitle := .Title }}
    {{ with .Params.items }}
        {{ range . }}
            {{ $mapItem := . }}
            {{ $mapUnique := printf "%s%s" $mapItem $mapDate }}
            {{ $mapUnique := replaceRE "^The |^An |^A " "" $mapUnique }}
            {{ $mapItems = merge $mapItems (
                dict $mapUnique (
                    slice $mapLink $mapItem $mapTitle
                )
            ) }}
        {{ end }}
    {{ end }}
{{ end }}

{{ $mapItems := dict }} creates a dictionary named $mapItems. Dictionary is a list of things where you have a key with attached value (one or many things).

I use $mapSomething for names because I decided to call the whole thing a site map. Can be named anything.

With {{ range .Site.RegularPages }} we want to look through all the pages we have. It’s a loop that goes through them. Maybe that’s too much, there are ways to narrow it down. But if a page doesn’t have items: in its front matter, it won’t show up anyway.

Then we create three variables $mapDate, $mapLink, and $mapTitle that we are going to work with. With $mapLink and $mapTitle we are just assigning them to be (:=) link and title of our pages.

With $mapDate, we also pipe it (|) into time.Format to look like a string of numbers, with two for each year, month, day, hours, minutes, and seconds. We will use it to make our keys look unique, so if we have two posts that share the same item, they will not override each other.

{{ with .Params.items }} limits our pages to only those that have items: in the front matter.

Then we create another loop {{ range . }}. . (dot) represents the thing we just worked with from the previous command. So, the items:.

{{ $mapItem := . }} creates another variable. These are the items.

Then, for simplicity and readability, we create our unique key with two commands. First, we join the name of the item with the date of the post:

{{ $mapUnique := printf "%s%s" $mapItem $mapDate }}

Second, we remove articles (“A”, “An”, “The”) if the names of the items begins with them. This is obviously unnecessary, but why not! {{ $mapUnique := replaceRE "^The |^An |^A " "" $mapUnique }}

Finally, we merge our dictionary (which is empty at the beginning) with the new entries we’ve created with our variables:

{{ $mapItems = merge $mapItems (
    dict $mapUnique (
        slice $mapLink $mapItem $mapTitle
    )
) }}

A bit of translation: $mapItems will now be equal to previous $mapItems plus new (dict …), where the first thing $mapUnique is a key and a second thing (slice …) is a value. The fact that it is a slice just means that there are multiple things in it and we can get them out individually.

To summarize, what we do is two loops. The first one goes through our posts and gets their date, link and title. Within it, so for each post, the second loop goes through our items: and adds them to our dictionary of things, with unique key and some stuff value that we will use to render our list.

List

Speaking of which, this is how we will render it:

<ul>
{{ range $key, $value := $mapItems }}
    <li><a
        title="From {{ index $value 2 }}"
        href="{{ index $value 0 }}">
        {{ index $value 1 }}
    </a></li>
{{ end }}
</ul>

We again use a loop, this time for the dictionary we created. It’s going to sort by key, that’s why we removed those articles so the list can be sorted in a nicer way.

In this loop, we use index to get the specific $value. They start from 0 and go as we set them with slice, post link, item, post title. Title is also unnecessary, but it will show up on hover and will be helpful if there are multiple items.

Conclusion

On my site map, I decided to split all items into multiple categories. I did it very simply, but in a way that is easy for me to work with. Instead of having just items: in front matter, I have three different things: iGames:, iCinema: and iMisc:. Then in the list.html, I repeated the second loop three times, for each of these three things ({{ with .Params.iGames }}, etc.), and each of them adds items to the corresponding dictionary ({{ $mapItemsGames := dict }}, etc.). Then I render every dictionary as its own list.

I am more than sure that there are other ways to accomplish the same thing. There are always different ways to manipulate data. Dictionary just made the most sense to me, with a key that can be used to sort things nicely and then pull things up from value to display in a way I want.