Hugo Extend Theme

Now we have a site up and running with one page, and we want to add another page.

We do this by running:

hugo new development/sites/hugo-extend-theme.md

This creates another page in our development section, and we can go to the site to see both pages listed:

Image here

Our site is currently ordering the pages by publish date, which is the default order. Since we have a series of posts we are writing, we will use a “weight” in the front-matter section to order the posts. In order to make this happen, we need to do 2 things:

1. Add a number field called weight to the front-matter to each page
2. Extend the default list template to order by weight

Add Weight Field

We can see that each Hugo Markdown file has a front-matter section with some metadata fenced by --- in it, like this:

---
title: "Hugo Extend Theme"
date: 2019-11-13T09:32:40-05:00
draft: true
---

To add a weight, we simply add a key (this snippet is yaml) so it looks like this:

---
title: "Hugo Extend Theme"
date: 2019-11-13T09:32:40-05:00
draft: true
weight: 110
---

Importantly, we set the first page to have a weight of 100, and the second page to have a higher weight. Our page that we want listed before this one should look like:

---
title: "Hugo Static Site Generator QuickStart"
date: 2019-11-13T07:32:41-05:00
draft: true
weight: 100
---

Extend Theme’s list Template

Now, we need to extend our theme’s list.html template to order the items by weight. To do this, first copy the template from the theme into the layout directory:

mkdir layouts/_default
cp themes/kiera/layouts/_default/list.html layouts/_default/

If Hugo finds a layouts/_default/list.html it will use that to override the one in the themes directory.

Note If you are using a different theme, change the directory name as needed.

Now, let’s look at the list template in layouts/_default/list.html:

{{ define "main" }}

<section id="list">

    {{ $baseurl := .Site.BaseURL }}

    {{ if eq .Data.Singular "tag" }}
        <h2>#{{ .Title | lower }}</h2>
    {{ else }}
        <h2>{{ .Title }}</h2>
    {{ end }}

    {{ .Content }}

    {{ range (.Paginate (.Data.Pages.GroupByDate "2006")).PageGroups  }}

    <h3>{{ .Key }}</h3>
    <ul>
        {{ range .Pages.ByWeight }}
        <li>
            <a href="{{ .Permalink }}">{{ if .Draft }}{{ T "draft" }}: {{end}}{{ .Title | markdownify }}</a>
            <time class="date-meta">{{ .Date.Format "Jan 2" }}</time>
        </li>
        {{ end }}
    </ul>

    {{ end }}

</section>

{{ template "_internal/pagination.html" . }}

{{ end }}

The part we are interested in changing is:

{{ range .Pages }}

The default is to order by date, but if we want to order by weight we can change it to:

{{ range .Pages.ByWeight }}

Sort by different fields

If we want to sort by a different field, all the information is here on the Hugo site: https://gohugo.io/templates/lists/

Conclusion

In this post, we saw how to add a weight to order pages, and how to extend a theme to override a template file.