diff --git a/content/content-management/front-matter.md b/content/content-management/front-matter.md index 87a87be3c..60aa1e63d 100644 --- a/content/content-management/front-matter.md +++ b/content/content-management/front-matter.md @@ -168,7 +168,7 @@ See [site configuration][config] for more information on Blackfriday configurati [contentorg]: /content-management/organization/ [content type]: /content-management/types/ [JSON Spec]: /documents/ecma-404-json-spec.pdf "Specification for JSON, JavaScript Object Notation" -[ordering]: /templates/ordering-and-grouping/ "Hugo provides multiple ways to sort and order your content in list templates" +[ordering]: /templates/lists/ "Hugo provides multiple ways to sort and order your content in list templates" [taxweight]: /content-management/taxonomies/ [TOML Spec]: https://github.com/toml-lang/toml "Specification for TOML, Tom's Obvious Minimal Language" [urls]: /content-management/urls/ diff --git a/content/content-management/taxonomies.md b/content/content-management/taxonomies.md index aadbec428..32b43266c 100644 --- a/content/content-management/taxonomies.md +++ b/content/content-management/taxonomies.md @@ -244,7 +244,7 @@ categories_weight: 44 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/). {{% /note %}} [`urlize` template function]: /functions/urlize/ diff --git a/content/functions/where.md b/content/functions/where.md index b2ce54a06..7ef59694c 100644 --- a/content/functions/where.md +++ b/content/functions/where.md @@ -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`): {{% code file="where-with-first.html" %}} ```html diff --git a/content/news/release-notes.md b/content/news/release-notes.md index 750bf723d..2aa2b3bac 100644 --- a/content/news/release-notes.md +++ b/content/news/release-notes.md @@ -760,7 +760,7 @@ This release represents over 110 code commits from 29 different contributors. * Streamlined [template organization](/templates/) * [Brand new docs site](http://gohugo.io/) * Support for publishDate which allows for posts to be dated in the future - * More [sort](/templates/ordering-and-grouping/) options + * More [sort](/templates/lists/) options * Logging support * Much better error handling * More informative verbose output @@ -774,7 +774,7 @@ This release represents over 110 code commits from 29 different contributors. This release represents over 110 code commits from 29 different contributors. * [Syntax highlighting](/tools/syntax-highlighting/) powered by pygments (**slow**) - * Ability to [sort content](/templates/ordering-and-grouping/) many more ways + * Ability to [sort content](/templates/lists/) many more ways * Automatic [table of contents](/content-management/toc/) generation * Support for Unicode URLs, aliases and indexes * Configurable per-section [permalink](/content-management/urls/) pattern support @@ -800,7 +800,7 @@ This release represents over 220 code commits from 22 different contributors. * Support for top level pages (in addition to homepage) * Complete overhaul of the documentation site * Full Windows support - * Better index support including [ordering by content weight](/templates/ordering-and-grouping/) + * Better index support including [ordering by content weight](/templates/lists/) * Add params to site config, available in .Site.Params from templates * Friendlier JSON support * Support for html & xml content (with front matter support) diff --git a/content/templates/lists.md b/content/templates/lists.md index eb385a5e4..4cd5dcc3f 100644 --- a/content/templates/lists.md +++ b/content/templates/lists.md @@ -1,6 +1,6 @@ --- -title: Introduction to Hugo Lists -linktitle: Hugo Lists Introduction +title: Lists of Content in Hugo +linktitle: List Page Templates 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//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//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/.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//layouts/_default/taxonomy.html` -### Taxonomy RSS +## Example List Templates -A Taxonomy’s RSS will be rendered at `///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: +{{% code file="layouts/section/post.html" %}} +```html +{{ partial "header.html" . }} +{{ partial "subheader.html" . }} -1. `/layouts/taxonomy/.rss.xml` -1. `/layouts/_default/rss.xml` -1. `/themes//layouts/taxonomy/.rss.xml` -1. `/themes//layouts/_default/rss.xml` +
+
+

{{ .Title }}

+
    + {{ range .Data.Pages }} + {{ .Render "li"}} + {{ end }} +
+
+
+{{ partial "footer.html" . }} +``` +{{% /code %}} -## List Page Variables +### Taxonomy Template -A list page is a `Page` and has all the [page variables][pagevars] -and [site variables][sitevars] available for use in templates. +{{% code file="layouts/_default/taxonomies.html" download="taxonomies.html" %}} +```html +{{ define "main" }} +
+
+

{{ .Title }}

+ {{ range .Data.Pages }} + {{ .Render "summary"}} + {{ end }} +
+
+{{ end }} +``` +{{% /code %}} -Taxonomy list pages will additionally have: +## Ordering Content -**.Data.`Singular`** The taxonomy itself.
[See Taxonomy Variables][taxvars] +Hugo lists render the content based on metadata provided in the [front matter](/content-management/front-matter/).. + +Here are a variety of different ways you can order the content items in +your list templates: + +### Default: Weight > Date + +{{% code file="layouts/partials/order-default.html" %}} +```html +
    + {{ range .Data.Pages }} +
  • +

    {{ .Title }}

    + +
    • + {{ end }} +
+``` +{{% /code %}} + +### By Weight + +{{% code file="layouts/partials/by-weight.html" %}} +```html +{{ range .Data.Pages.ByWeight }} +
  • + {{ .Title }} +
    {{ .Date.Format "Mon, Jan 2, 2006" }}
    +
    • +{{ end }} +``` +{{% /code %}} + +### By Date + +{{% code file="layouts/partials/by-date.html" %}} +```html +{{ range .Data.Pages.ByDate }} +
  • + {{ .Title }} +
    {{ .Date.Format "Mon, Jan 2, 2006" }}
    +
    • +{{ end }} +``` +{{% /code %}} + +### By Publish Date + +{{% code file="layouts/partials/by-publish-date.html" %}} +```html +{{ range .Data.Pages.ByPublishDate }} +
  • + {{ .Title }} +
    {{ .PublishDate.Format "Mon, Jan 2, 2006" }}
    +
    • +{{ end }} +``` +{{% /code %}} + +### By Expiration Date + +{{% code file="layouts/partials/by-expiry-date.html" %}} +```html +{{ range .Data.Pages.ByExpiryDate }} +
  • + {{ .Title }} +
    {{ .ExpiryDate.Format "Mon, Jan 2, 2006" }}
    +
    • +{{ end }} +``` +{{% /code %}} + +### By Last Modified Date + +{{% code file="layouts/partials/by-last-mod.html" %}} +```html +{{ range .Data.Pages.ByLastmod }} +
  • + {{ .Title }} +
    {{ .Date.Format "Mon, Jan 2, 2006" }}
    +
    • +{{ end }} +``` +{{% /code %}} + +### By Length + +{{% code file="layouts/partials/by-length.html" %}} +```html +{{ range .Data.Pages.ByLength }} +
  • + {{ .Title }} +
    {{ .Date.Format "Mon, Jan 2, 2006" }}
    +
    • +{{ end }} +``` +{{% /code %}} + + +### By Title + +{{% code file="layouts/partials/by-title.html" %}} +```html +{{ range .Data.Pages.ByTitle }} +
  • + {{ .Title }} +
    {{ .Date.Format "Mon, Jan 2, 2006" }}
    +
    • +{{ end }} +``` +{{% /code %}} + +### By Link Title + +{{% code file="layouts/partials/by-link-title.html" %}} +```html +{{ range .Data.Pages.ByLinkTitle }} +
  • + {{ .LinkTitle }} +
    {{ .Date.Format "Mon, Jan 2, 2006" }}
    +
    • +{{ 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. + +{{% code file="layouts/partials/by-rating.html" %}} +```html +{{ range (.Data.Pages.ByParam "rating") }} + +{{ end }} +``` +{{% /code %}} + +If the front matter field of interest is nested beneath another field, you can +also get it: + +{{% code file="layouts/partials/by-nested-param.html" %}} +```html +{{ range (.Date.Pages.ByParam "author.last_name") }} + +{{ end }} +``` +{{% /code %}} + +### Reverse Order + +Reversing order can be applied to any of the above methods. The following uses `ByDate` as an example: + +{{% code file="layouts/partials/by-date-reverse.html" %}} +```html +{{ range .Data.Pages.ByDate.Reverse }} +
  • +{{ .Title }} +
    {{ .Date.Format "Mon, Jan 2, 2006" }}
    +
    • +{{ end }} +``` +{{% /code %}} + +## Grouping Content + +Hugo provides some functions for grouping pages by Section, Type, Date, etc. + +### By Page Field + +{{% code file="layouts/partials/by-page-field.html" %}} +```html +{{ range .Data.Pages.GroupBy "Section" }} +

    {{ .Key }}

    +
      + {{ range .Pages }} +
    • + {{ .Title }} +
      {{ .Date.Format "Mon, Jan 2, 2006" }}
      +
      • + {{ end }} +
    +{{ end }} +``` +{{% /code %}} + +### By Page date + +{{% code file="layouts/partials/by-page-date.html" %}} +```html +{{ range .Data.Pages.GroupByDate "2006-01" }} +

    {{ .Key }}

    +
      + {{ range .Pages }} +
    • + {{ .Title }} +
      {{ .Date.Format "Mon, Jan 2, 2006" }}
      +
      • + {{ end }} +
    +{{ end }} +``` +{{% /code %}} + +### By Page publish date + +{{% code file="layouts/partials/by-page-publish-date.html" %}} +```html +{{ range .Data.Pages.GroupByPublishDate "2006-01" }} +

    {{ .Key }}

    +
      + {{ range .Pages }} +
    • + {{ .Title }} +
      {{ .PublishDate.Format "Mon, Jan 2, 2006" }}
      +
      • + {{ end }} +
    +{{ end }} +``` +{{% /code %}} + +### By Page Param + +{{% code file="layouts/partials/by-page-param.html" %}} +```html +{{ range .Data.Pages.GroupByParam "param_key" }} +

    {{ .Key }}

    +
      + {{ range .Pages }} +
    • + {{ .Title }} +
      {{ .Date.Format "Mon, Jan 2, 2006" }}
      +
      • + {{ end }} +
    +{{ end }} +``` +{{% /code %}} + +### By Page Param in Date Format + +{{% code file="layouts/partials/by-page-param-as-date.html" %}} +```html +{{ range .Data.Pages.GroupByParamDate "param_key" "2006-01" }} +

    {{ .Key }}

    +
      + {{ range .Pages }} +
    • + {{ .Title }} +
      {{ .Date.Format "Mon, Jan 2, 2006" }}
      +
      • + {{ end }} +
    +{{ 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. + +{{% code file="layouts/partials/by-group-by-page.html" %}} +```html +{{ range .Data.Pages.GroupByDate "2006-01" "asc" }} +

    {{ .Key }}

    +
      + {{ range .Pages.ByTitle }} +
    • + {{ .Title }} +
      {{ .Date.Format "Mon, Jan 2, 2006" }}
      +
      • + {{ end }} +
    +{{ 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/).) -{{% /note %}} [directorystructure]: /getting-started/directory-structure/ [homepage]: /templates/homepage/ @@ -84,5 +459,6 @@ If `where` or `first` receives invalid input or a field name that doesn’t exis [sectiontemps]: /templates/section-templates/ [sitevars]: /variables/site/ [taxlists]: /templates/taxonomy-templates/#taxonomy-list-templates/ -[taxvars]: /variables/taxonomy/ [taxterms]: /templates/taxonomy-templates/#taxonomy-terms-templates/ +[taxvars]: /variables/taxonomy/ +[views]: /templates/views/ diff --git a/content/templates/ordering-and-grouping.md b/content/templates/ordering-and-grouping.md index 452157d88..b62c35582 100644 --- a/content/templates/ordering-and-grouping.md +++ b/content/templates/ordering-and-grouping.md @@ -8,9 +8,10 @@ lastmod: 2017-02-01 categories: [templates] tags: [] weight: 27 -draft: false +draft: true aliases: [/templates/ordering/,/templates/grouping/] toc: true +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. diff --git a/content/templates/taxonomy-templates.md b/content/templates/taxonomy-templates.md index aff73ee34..5218a4f77 100644 --- a/content/templates/taxonomy-templates.md +++ b/content/templates/taxonomy-templates.md @@ -310,6 +310,7 @@ This example will list all taxonomies and their terms, as well as all the conten [delimit]: /functions/delimit/ +[lists]: /templates/lists/ [renderlists]: /templates/lists/ [single page template]: /templates/single-page-templates/ [sitevars]: /variables/site/ \ No newline at end of file