By using taxonomic weight, the same piece of content can appear in different positions in different taxonomies.
{{% note "Limits to Ordering Taxonomies" %}}
Currently taxonomies only support the [default `weight => date` ordering of list content](/templates/ordering-and-grouping/#default-weight-date). For more information, see the documentation on [taxonomy templates](/templates/taxonomy-templates/).
Currently taxonomies only support the [default `weight => date` ordering of list content](/templates/lists/#default-weight-date). For more information, see the documentation on [taxonomy templates](/templates/taxonomy-templates/).
@@ -100,7 +100,7 @@ You can also put the returned value of the `where` clauses into a variable:
## Using `where` with `first`
The following grabs the first five content files in `post` using the [default ordering](/templates/ordering-and-grouping/) for lists (i.e., `weight => date`):
The following grabs the first five content files in `post` using the [default ordering](/templates/lists/) for lists (i.e., `weight => date`):
description: Lists have a specific meaning and usage in Hugo when it comes to rendering your site homepage, section page, taxonomy list, or taxonomy terms list.
date: 2017-02-01
publishdate: 2017-02-01
@@ -11,12 +11,11 @@ weight: 22
draft: false
aliases: [/templates/list/,/layout/indexes/]
toc: true
wip: true
---
## What is a List Page Template?
A list page template is a template used to render multiple pieces of content in a single HTML page. The exception to this rule is the homepage, which is still a list but has its own [dedicated template][homepage]).
A list page template is a template used to render multiple pieces of content in a single HTML page. The exception to this rule is the homepage, which is still a list but has its own [dedicated template][homepage].
Hugo uses the term *list* in its truest sense; i.e. a sequential arrangement of material, especially in alphabetical or numerical order. Hugo uses list templates on any output HTML page where content is traditionally listed:
@@ -33,43 +32,419 @@ The idea of a list page comes from the [hierarchical mental model of the web][me
### Default Templates
Since section lists and taxonomy lists (N.B., *not* [taxonomy terms lists][taxterms]) are both *lists* with regards to their templates, both have the same terminating default of `_default/list.html`---or `themes/<THEME>/layouts/_default/list.html` in the case of a themed project---in their *lookup orders*. In addition, both [section lists][sectiontemps] and [taxonomy lists][taxlists] have their own default list templates in `_default`:
Since section lists and taxonomy lists (N.B., *not* [taxonomy terms lists][taxterms]) are both *lists* with regards to their templates, both have the same terminating default of `_default/list.html`or `themes/<THEME>/layouts/_default/list.html` in their lookup order. In addition, both [section lists][sectiontemps] and [taxonomy lists][taxlists] have their own default list templates in `_default`:
#### Default Section Templates
1.`layouts/section/<SECTIONNAME>.html`
2.`layouts/section/list.html`
3.`layouts/_default/section.html`
4.`layouts/_default/list.html`
1.`layouts/_default/section.html`
2.`layouts/_default/list.html`
#### Default Taxonomy List Templates
1.`layouts/_default/taxonomy.html`
2.`themes/<THEME>/layouts/_default/taxonomy.html`
### Taxonomy RSS
## Example List Templates
A Taxonomy’s RSS will be rendered at `/<PLURAL>/<TERM>/index.xml` (e.g. http://spf13.com/topics/golang/index.xml).
### Section Template
{{% note %}}
Most use cases will find that the [RSS 2.0][] template that ships with Hugo is sufficient for their needs.
{{% /note %}}
This list template is used for [spf13.com](http://spf13.com/). It makes use of [partial templates][partials]. All examples use a [view](/templates/views/) called either "li" or "summary."
Hugo provides the ability for you to define any RSS type you wish. You can can have different RSS files for each section and taxonomy:
<divclass="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
```
{{% /code %}}
### 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.
{{ range .Data.Pages.GroupByParamDate "param_key" "2006-01" }}
<h3>{{ .Key }}</h3>
<ul>
{{ range .Pages }}
<li>
<ahref="{{ .Permalink }}">{{ .Title }}</a>
<divclass="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
</ul>
{{ end }}
```
{{% /code %}}
### Reversing 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
```html
{{ range (.Data.Pages.GroupBy "Section").Reverse }}
```
```html
{{ range (.Data.Pages.GroupByDate "2006-01").Reverse }}
```
#### Providing the Alternate Direction
```html
{{ range .Data.Pages.GroupByDate "2006-01" "asc" }}
```
```html
{{ range .Data.Pages.GroupBy "Section" "desc" }}
```
### Ordering 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.
{{ range .Data.Pages.GroupByDate "2006-01" "asc" }}
<h3>{{ .Key }}</h3>
<ul>
{{ range .Pages.ByTitle }}
<li>
<ahref="{{ .Permalink }}">{{ .Title }}</a>
<divclass="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
</ul>
{{ end }}
```
{{% /code %}}
## Filtering and Limiting Lists
Sometimes you only want to list a subset of the available content. A common request is to only display “Posts” on the homepage. You can accomplish this with the `where` function.
### `where`
`where` works in a similar manner to the `where` keyword in SQL. It selects all elements of the array or slice that match the provided field and value. `where` takes three arguments:
1.`array` or a `slice of maps or structs`
2.`key` or `field name`
3.`match value`
{{% code file="layouts/_default/.html" %}}
```html
{{ range where .Data.Pages "Section" "post" }}
{{ .Content }}
{{ end }}
```
{{% /code %}}
### `first`
`first` works in a similar manner to the [`limit` keyword in SQL][limitkeyword]. It reduces the array to only the `first N` elements. It takes the array and number of elements as input. `first` takes two arguments:
1.`array` or `slice of maps or structs`
2.`number of elements`
{{% code file="layout/_default/section.html" %}}
```html
{{ range first 10 .Data.Pages }}
{{ .Render "summary" }}
{{ end }}
```
{{% /code %}}
### `first` and `where` Together
Using `first` and `where` together can be very powerful:
{{% code file="first-and-where-together.html" %}}
```html
{{ range first 5 (where .Data.Pages "Section" "post") }}
{{ .Content }}
{{ end }}
```
{{% /code %}}
{{% note %}}
If `where` or `first` receives invalid input or a field name that doesn’t exist, it will return an error and stop site generation. `where` and `first` also work on taxonomy list templates *and* taxonomy terms templates. (See [Taxonomy Templates](/templates/taxonomy-templates/).)
notes: This was originally going to be a separate page on the new docs site but it now makes more sense to keep everything within the templates/lists page. - rdwatters, 2017-03-12.
---
In Hugo, A list template is any template that will be used to render multiple pieces of content in a single HTML page.
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Ryan Watters