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.
## Example List Templates
### Section Template
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."
<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.
{{<codefile="layouts/partials/by-rating.html">}}
{{ range (.Data.Pages.ByParam "rating") }}
<!-- ... -->
{{ end }}
{{</code>}}
If the front matter field of interest is nested beneath another field, you can
{{ 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>}}
### 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 (.Data.Pages.GroupBy "Section").Reverse }}
```
```
{{ range (.Data.Pages.GroupByDate "2006-01").Reverse }}
```
#### Provide the Alternate Direction
```
{{ range .Data.Pages.GroupByDate "2006-01" "asc" }}
```
```
{{ range .Data.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.
{{ 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>}}
## Filter 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`
{{<codefile="layouts/_default/.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`
{{<codefile="layout/_default/section.html">}}
{{ range first 10 .Data.Pages }}
{{ .Render "summary" }}
{{ end }}
{{</code>}}
### `first` and `where` Together
Using `first` and `where` together can be very powerful:
{{<codefile="first-and-where-together.html">}}
{{ range first 5 (where .Data.Pages "Section" "post") }}
