Ordere and Grouping Hugo Lists

You can group or order your content in both your templating and content front matter.

In Hugo, A list template is any template that will be used to render multiple pieces of content in a single HTML page.

Example List Templates

Section Template

This list template is used for spf13.com . It makes use of [partial templates][partials]. All examples use a view called either “li” or “summary.”

layouts/section/post.html

{{ partial "header.html" . }}
{{ partial "subheader.html" . }}

<section id="main">
  <div>
   <h1 id="title">{{ .Title }}</h1>
        <ul id="list">
            {{ range .Pages }}
                {{ .Render "li"}}
            {{ end }}
        </ul>
  </div>
</section>
{{ partial "footer.html" . }}

Taxonomy Template

layouts/_default/taxonomies.html

{{ define "main" }}
<section id="main">
  <div>
   <h1 id="title">{{ .Title }}</h1>
    {{ range .Pages }}
        {{ .Render "summary"}}
    {{ end }}
  </div>
</section>
{{ end }}

Order Content

Hugo lists render the content based on metadata provided in the front matter ..

Here are a variety of different ways you can order the content items in your list templates:

Default: Weight > Date

layouts/partials/order-default.html

<ul class="pages">
    {{ range .Pages }}
        <li>
            <h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1>
            <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time>
        </li>
    {{ end }}
</ul>

By Weight

layouts/partials/by-weight.html

{{ range .Pages.ByWeight }}
    <li>
    <a href="{{ .Permalink }}">{{ .Title }}</a>
    <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
    </li>
{{ end }}

By Date

layouts/partials/by-date.html

{{ range .Pages.ByDate }}
    <li>
    <a href="{{ .Permalink }}">{{ .Title }}</a>
    <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
    </li>
{{ end }}

By Publish Date

layouts/partials/by-publish-date.html

{{ range .Pages.ByPublishDate }}
    <li>
    <a href="{{ .Permalink }}">{{ .Title }}</a>
    <div class="meta">{{ .PublishDate.Format "Mon, Jan 2, 2006" }}</div>
    </li>
{{ end }}

By Expiration Date

layouts/partials/by-expiry-date.html

{{ range .Pages.ByExpiryDate }}
    <li>
    <a href="{{ .Permalink }}">{{ .Title }}</a>
    <div class="meta">{{ .ExpiryDate.Format "Mon, Jan 2, 2006" }}</div>
    </li>
{{ end }}

By Last Modified Date

layouts/partials/by-last-mod.html

{{ range .Pages.ByLastmod }}
    <li>
    <a href="{{ .Permalink }}">{{ .Title }}</a>
    <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
    </li>
{{ end }}

By Length

layouts/partials/by-length.html

{{ range .Pages.ByLength }}
    <li>
    <a href="{{ .Permalink }}">{{ .Title }}</a>
    <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
    </li>
{{ end }}

By Title

layouts/partials/by-title.html

{{ range .Pages.ByTitle }}
    <li>
    <a href="{{ .Permalink }}">{{ .Title }}</a>
    <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
    </li>
{{ end }}

By Link Title

layouts/partials/by-link-title.html

{{ range .Pages.ByLinkTitle }}
    <li>
    <a href="{{ .Permalink }}">{{ .LinkTitle }}</a>
    <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
    </li>
{{ end }}

By Parameter

Order based on the specified front matter parameter. Content that does not have the specified front matter field will use the site’s .Site.Params default. If the parameter is not found at all in some entries, those entries will appear together at the end of the ordering.

The below example sorts a list of posts by their rating.

layouts/partials/by-rating.html

{{ range (.Pages.ByParam "rating") }}
  <!-- ... -->
{{ end }}

If the front matter field of interest is nested beneath another field, you can also get it:

layouts/partials/by-nested-param.html

{{ range (.Pages.ByParam "author.last_name") }}
  <!-- ... -->
{{ end }}

Reverse Order

Reversing order can be applied to any of the above methods. The following uses ByDate as an example:

layouts/partials/by-date-reverse.html

{{ range .Pages.ByDate.Reverse }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}

Group Content

Hugo provides some functions for grouping pages by Section, Type, Date, etc.

By Page Field

layouts/partials/by-page-field.html

{{ range .Pages.GroupBy "Section" }}
<h3>{{ .Key }}</h3>
<ul>
    {{ range .Pages }}
    <li>
    <a href="{{ .Permalink }}">{{ .Title }}</a>
    <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
    </li>
    {{ end }}
</ul>
{{ end }}

By Page date

layouts/partials/by-page-date.html

{{ range .Pages.GroupByDate "2006-01" }}
<h3>{{ .Key }}</h3>
<ul>
    {{ range .Pages }}
    <li>
    <a href="{{ .Permalink }}">{{ .Title }}</a>
    <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
    </li>
    {{ end }}
</ul>
{{ end }}

By Page publish date

layouts/partials/by-page-publish-date.html

{{ range .Pages.GroupByPublishDate "2006-01" }}
<h3>{{ .Key }}</h3>
<ul>
    {{ range .Pages }}
    <li>
    <a href="{{ .Permalink }}">{{ .Title }}</a>
    <div class="meta">{{ .PublishDate.Format "Mon, Jan 2, 2006" }}</div>
    </li>
    {{ end }}
</ul>
{{ end }}

By Page Param

layouts/partials/by-page-param.html

{{ range .Pages.GroupByParam "param_key" }}
<h3>{{ .Key }}</h3>
<ul>
    {{ range .Pages }}
    <li>
    <a href="{{ .Permalink }}">{{ .Title }}</a>
    <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
    </li>
    {{ end }}
</ul>
{{ end }}

By Page Param in Date Format

layouts/partials/by-page-param-as-date.html

{{ range .Pages.GroupByParamDate "param_key" "2006-01" }}
<h3>{{ .Key }}</h3>
<ul>
    {{ range .Pages }}
    <li>
    <a href="{{ .Permalink }}">{{ .Title }}</a>
    <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
    </li>
    {{ end }}
</ul>
{{ end }}

Reverse Key Order

The ordering of the groups is performed by keys in alphanumeric order (A–Z, 1–100) and in reverse chronological order (newest first) for dates.

While these are logical defaults, they are not always the desired order. There are two different syntaxes to change the order, both of which work the same way. You can use your preferred syntax.

Reverse Method

{{ range (.Pages.GroupBy "Section").Reverse }}

{{ range (.Pages.GroupByDate "2006-01").Reverse }}

Provide the Alternate Direction

{{ range .Pages.GroupByDate "2006-01" "asc" }}

{{ range .Pages.GroupBy "Section" "desc" }}

Order Within Groups

Because Grouping returns a {{.Key}} and a slice of pages, all of the ordering methods listed above are available.

In the following example, groups are ordered chronologically and then content within each group is ordered alphabetically by title.

layouts/partials/by-group-by-page.html

{{ range .Pages.GroupByDate "2006-01" "asc" }}
<h3>{{ .Key }}</h3>
<ul>
    {{ range .Pages.ByTitle }}
    <li>
    <a href="{{ .Permalink }}">{{ .Title }}</a>
    <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
    </li>
    {{ end }}
</ul>
{{ end }}

Filter and Limiting Lists

See the Lists/Filtering and Limiting Lists section for details.

Edit this file on GitHub

Last updated: February 1, 2017