Ryan Watters
4.5 KiB
title, linktitle, description, date, publishdate, lastmod, categories, tags, weight, draft, aliases, toc, needsreview
| title | linktitle | description | date | publishdate | lastmod | categories | tags | weight | draft | aliases | toc | needsreview | |||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Introduction to Lists in Hugo | Hugo Lists | Lists have a specific meaning and usage in Hugo. If you want to know how to render your site homepage, section homepage, taxonomy list, or taxonomy terms list, start here. | 2017-02-01 | 2017-02-01 | 2017-02-01 |
|
|
22 | false |
|
true | 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 (with the exception of the homepage, which has a dedicated template).
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:
The idea of a list page comes from the hierarchical mental model of the web and is best demonstrated visually:
---
aliases:
- /doc/using-index-md/
lastmod: 2017-02-22
date: 2017-02-22
linktitle: Using _index.md
menu:
main:
parent: content
prev: /content/example
next: /themes/overview
notoc: true
title: Using _index.md
weight: 70
---
List Defaults
Default Templates
Since section lists and taxonomy lists (N.B., not [taxonomy terms lists][]) 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][sectiontemplates] and [taxonomy lists][taxonomies] have their own default list templates in _default:
Default Section Templates
layouts/section/<SECTIONNAME>.htmllayouts/section/list.htmllayouts/_default/section.htmllayouts/_default/list.html
Understanding .Data.Pages
Taxonomy Lists
A Taxonomy will be rendered at /PLURAL/TERM/ (e.g. http://spf13.com/topics/golang/) from:
- /layouts/taxonomy/
SINGULAR.html (e.g./layouts/taxonomy/topic.html) - /layouts/_default/taxonomy.html
- /layouts/_default/list.html
- /themes/
THEME/layouts/taxonomy/SINGULAR.html - /themes/
THEME/layouts/_default/taxonomy.html - /themes/
THEME/layouts/_default/list.html
Note that a taxonomy list page can also have a content file with front matter, see Source Organization.
Taxonomy RSS
A Taxonomy’s RSS will be rendered at /PLURAL/TERM/index.xml (e.g. http://spf13.com/topics/golang/index.xml)
Hugo ships with its own RSS 2.0 template. In most cases this will be sufficient, and an RSS template will not need to be provided by the user.
Hugo provides the ability for you to define any RSS type you wish, and can have different RSS files for each section and taxonomy.
- /layouts/taxonomy/
SINGULAR.rss.xml - /layouts/_default/rss.xml
- /themes/
THEME/layouts/taxonomy/SINGULAR.rss.xml - /themes/
THEME/layouts/_default/rss.xml
Variables
A list page is a Page and have all the page variables
and site variables available to use in the templates.
Taxonomy pages will additionally have:
.Data.Singular The taxonomy itself.
{{% 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.)
{{% /note %}}