Understanding Hugo functions

Hi Everyone,

I am a new used to Hugo and I’ve been developing my own site and Theme. I’ve got the basic wireframe built, I’ve managed to get compiled CSS working. I am having trouble getting my head around Hugo Functions and how they work. In an effort to solve this, I have read almost the entirety of the current Hugo Docs site, watched all the Hugo Youtube clips and read Google for hours. I am still struggling to understand Hugo Functions. I’ve also read 50 or more range posts here in the hopes I might understand.

For example, I want to get a list of categories for my blog. I will use this on my front page and when you go to /blog/

The function I am using is:

	    {{ range $key, $value := .Site.Taxonomies.categories }}
        <a class=blog-panel-category item{{ printf "%s/%s" $key }}
        href="/categories/{{ $value | urlize }}">{{ $key | title }}</a>
    {{ end }}

I would like to get the index for each of the entries, hence item{{ printf "%s/%s" $key }}, which does not seem to work. I am using this in my CSS.

I would like to order the categories based on the number of articles each category has (ascending).

On my front page, I would like to restrict the number of categories returned to 9.

On my /blog/ page, I want to sort alphabetically.

I do not understand what the $key, $value values that are returned and why they change when I change the function from .Site.Taxonomies.categories to .Site.Taxonomies.categories.Alphabetical.Reverse. I am also not understanding scope when I have functions that are nested, like this example - Reverse taxonomy order

I was wondering if someone could give me some function examples on how to create what I want but also explain some of my questions above or point me towards an article that explains things in newbie terms?


I’m not sure I understand what you are trying to do, especially around:

Could you give a sample output value this should resolve to?

Is this supposed to be part of the class attribute? / is not a valid character.

{{ range .Site.Taxonomies.categories.ByCount.Reverse }}
  {{.Term}}: {{.Count}} <br>
{{ end }}
{{ range first 9 .Site.Taxonomies.categories.ByCount.Reverse }}
  {{.Term}}: {{.Count}} <br>
{{ end }}
{{ range $index, $element := .Site.Taxonomies.categories.Alphabetical }}
  {{$element.Term}} : {{$element.Count}} <br>
{{ end }}

Docs: Introduction to Hugo Templating | Hugo

  1. Looking at Example #3 and #4 in the link above, range-ing in the pattern of
{{ range $a, $b := $x }}

has slightly different implications depending on what $x is.

Case 1: If $x is an array: $a is the index, $b is the element (Example #3).

Case 2: If $x is a map: $a is the key, $b is the value (Example #4).

So taking the following example:

{{ range $a, $b := $x }}
  {{ $a }} : {{ $b }}
{{ end }}

Case 1:

$x has value ["banana","blueberry","apple"]


0 : banana
1 : blueberry
2 : apple

Case 2:

$x is a map with the value:
  "fruit": "banana",
  "color": "yellow",
  "variety": "cavendish"


color : yellow,
fruit : banana,
variety : cavendish

* note that as a map is unordered, the order of results printed may vary.

  1. This distinction matters because .Site.Taxonomies.categories returns an unordered map, while .Site.Taxonomies.categories.Alphabetical.Reverse returns an OrderedTaxonomy, which you can think of as an ordered array. So in ...Alphabetical.... the $key is actually the index.



This was me trying to explain what I was doing. I was attempting to get the index value from the range function, I found it on some discourse post here or on the web. I would still like to get the index value from the range function so I can use it in my CSS.

Thank you for the remaining answers, I will read about what you wrote about.

On a side note, I would love it if the docs could be a little more clear on how functions work the way they do, especially why .Site.Taxonomies.categories returns something very different to .Site.Taxonomies.categories.Alphabetical. This created much confusion for me.

What do they return? Please share the output.

Thank you for contributing to my question @maiki

@maiki The answer to your question has already been provided by @pointyfar