Tips and tricks for building a theme in Hugo

Jeff McMorris
4 min readFeb 29, 2016

So I am learning how to build a theme in hugo and wanted to document the things I found that were not obvious to me.

  1. To add a list of categories with counts of articles in each category use this snippet I found in the hugo-icarus theme.
{{ range $name, $items := .Site.Taxonomies.categories }}
<li><a href="{{ $.Site.BaseURL }}categories/{{ $name | urlize | lower }}">{{ $name }} &nbsp;<span>({{ len $items }})</span></a></li>
{{ end }}

2. To add custom global variables.

in your config.toml or theme.toml[params]
myvariable = "testing 123"

mysubvariable = "more tests"
in your theme file.{{ .Site.Params.myvariable }}
{{ .Site.Params.general.mysubvariable }}
Don't forget to restart hugo if you make changes to the .toml files. If you don't these variables you added will not show up.

3. To show a list of tags.

{{ range $name, $taxonomy := .Site.Taxonomies.tags }}
<a href="/tags/{{ $name | urlize }}">{{ $name }}</a>
{{ end }}

4. To show the most recent three posts with dates in format 9 hours ago, 3 days ago etc. Install timeago javascript plugin. In hugo insert this in your theme.

{{ range first 3 .Site.Pages }}
<h5><a href="{{ .Permalink }}">{{ .Title }}</a></h5>
<time class="timeago" datetime='{{ .Date.Format "2006-01-02T15:04:05-07:00" }}'>{{ .Date }}</time>
{{ end }}

5. To show a list of posts for a specific tag. In this case I have a tag named featured.

{{ range .Site.Taxonomies.tags.featured }}
<h5><a href="{{ .Page.Permalink }}">{{ .Page.Title }}</a></h5>
<time class="timeago" datetime='{{ .Page.Date.Format "2006-01-02T15:04:05-07:00" }}'>{{ .Page.Date }}</time>
{{ end }}

6. If you have an article and you want to change the breakpoint of the summary text for an article you can add a more comment where you want the summary to end.


7. You can combine first and after to make a more complicated query. I am showing 3 featured posts after skipping the first one. I am also showing a featured_image that was in the content markdown in the front matter. This is the top area with the title and other parameters in your markdown…