Alphabetical

The Alphabetical method on a Taxonomy object returns an ordered taxonomy, sorted alphabetically by term.

While a Taxonomy object is a map, an ordered taxonomy is a slice, where each element is an object that contains the term and a slice of its weighted pages.

Before we can use a Taxonomy method, we need to capture a Taxonomy object.

Capture a Taxonomy object

Consider this site configuration:

taxonomies:
  author: authors
  genre: genres

[taxonomies]
  author = 'authors'
  genre = 'genres'

{
   "taxonomies": {
      "author": "authors",
      "genre": "genres"
   }
}

And this content structure:

content/
├── books/
│   ├── and-then-there-were-none.md --> genres: suspense
│   ├── death-on-the-nile.md        --> genres: suspense
│   └── jamaica-inn.md              --> genres: suspense, romance
│   └── pride-and-prejudice.md      --> genres: romance
└── _index.md

To capture the “genres” Taxonomy object from within any template, use the Taxonomies method on a Site object.

{{ $taxonomyObject := .Site.Taxonomies.genres }}

To capture the “genres” Taxonomy object when rendering its page with a taxonomy template, use the Terms method on the page’s Data object:

{{ $taxonomyObject := .Data.Terms }}

To inspect the data structure:

<pre>{{ debug.Dump $taxonomyObject }}</pre>

Although the Alphabetical and ByCount methods provide a better data structure for ranging through the taxonomy, you can render the weighted pages by term directly from the Taxonomy object:

{{ range $term, $weightedPages := $taxonomyObject }}
  <h2><a href="{{ .Page.RelPermalink }}">{{ .Page.LinkTitle }}</a></h2>
  <ul>
    {{ range $weightedPages }}
      <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
    {{ end }}
  </ul>
{{ end }}

In the example above, the first anchor element is a link to the term page.

Get the ordered taxonomy

Now that we have captured the “genres” Taxonomy object, let’s get the ordered taxonomy sorted alphabetically by term:

{{ $taxonomyObject.Alphabetical }}

To reverse the sort order:

{{ $taxonomyObject.Alphabetical.Reverse }}

To inspect the data structure:

<pre>{{ debug.Dump $taxonomyObject.Alphabetical }}</pre>

An ordered taxonomy is a slice, where each element is an object that contains the term and a slice of its weighted pages.

Each element of the slice provides these methods:

Count

(int) Returns the number of pages to which the term is assigned.

Page

(page.Page) Returns the term’s Page object, useful for linking to the term page.

Pages

(page.Pages) Returns a Pages object containing the Page objects to which the term is assigned, sorted by taxonomic weight. To sort or group, use any of the methods available to the Pages object. For example, sort by the last modification date.

Term

(string) Returns the term name.

WeightedPages

(page.WeightedPages) Returns a slice of weighted pages to which the term is assigned, sorted by taxonomic weight. The Pages method above is more flexible, allowing you to sort and group.

Example

With this template:

{{ range $taxonomyObject.Alphabetical }}
  <h2><a href="{{ .Page.RelPermalink }}">{{ .Page.LinkTitle }}</a> ({{ .Count }})</h2>
  <ul>
    {{ range .Pages.ByTitle }}
      <li><a href="{{ .RelPermalink }}">{{ .Title }}</a></li>
    {{ end }}
  </ul>
{{ end }}

Hugo renders:

<h2><a href="/genres/romance/">romance</a> (2)</h2>
<ul>
  <li><a href="/books/jamaica-inn/">Jamaica inn</a></li>
  <li><a href="/books/pride-and-prejudice/">Pride and prejudice</a></li>
</ul>
<h2><a href="/genres/suspense/">suspense</a> (3)</h2>
<ul>
  <li><a href="/books/and-then-there-were-none/">And then there were none</a></li>
  <li><a href="/books/death-on-the-nile/">Death on the nile</a></li>
  <li><a href="/books/jamaica-inn/">Jamaica inn</a></li>
</ul>