From b108e5eeac9441f0b61906aaeacb27086b91dd1f Mon Sep 17 00:00:00 2001 From: Ryan Watters Date: Fri, 24 Feb 2017 20:04:22 -0600 Subject: [PATCH] Make first round of edits to ordering and grouping lists page --- content/templates/lists.md | 372 +----------------- .../templates/ordering-and-grouping-lists.md | 365 ++++++++++++++++- 2 files changed, 374 insertions(+), 363 deletions(-) diff --git a/content/templates/lists.md b/content/templates/lists.md index ad20ce816..d0f3828ef 100644 --- a/content/templates/lists.md +++ b/content/templates/lists.md @@ -1,7 +1,7 @@ --- title: Introduction to Lists in Hugo -linktitle: Lists in Hugo -description: +linktitle: Hugo Lists Introduction +description: 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. date: 2017-02-01 publishdate: 2017-02-01 lastmod: 2017-02-01 @@ -20,7 +20,7 @@ A list page template is a template used to render multiple pieces of content in Hugo uses the term *list* in its truest sense: a sequential arrangement of material, especially in alphabetical or numerical order. Hugo uses list templates on any output HTML page where content is being listed (e.g., [taxonomies][], [sections][], and [RSS][]). The idea of a list page comes from the [hierarchical mental model of the web][mentalmodel] and is best demonstrated visually: - +```yaml --- aliases: - /doc/using-index-md/ @@ -36,7 +36,9 @@ notoc: true title: Using _index.md weight: 70 --- -# \_index.md and 'Everything is a Page' +``` + +## \_index.md and 'Everything is a Page' As of version v0.18 Hugo now treats '[everything as a page](http://bepsays.com/en/2016/12/19/hugo-018/)'. This allows you to add content and front matter to any page - including List pages like [Sections](/content/sections/), [Taxonomies](/taxonomies/overview/), [Taxonomy Terms pages](/templates/terms/) and even to potential 'special case' pages like the [Home page](/templates/homepage/). @@ -48,7 +50,7 @@ In order to take advantage of this behaviour you need to do a few things. 3. Ensure that the respective template is configured to display `{{ .Content }}` if you wish for the content of the \_index.md file to be rendered on the respective page. -## How \_index.md pages work +### How \_index.md pages work Before continuing it's important to know that this page must reference certain templates to describe how the \_index.md page will be rendered. Hugo has a multitude of possible templates that can be used and placed in various places (think theme templates for instance). For simplicity/brevity the default/top level template location will be used to refer to the entire range of places the template can be placed. @@ -74,10 +76,12 @@ Let's put all this information together: Here are a couple of examples to make it clearer... +``` | \_index.md location | Page affected | Rendered by | | ------------------- | ------------ | ----------- | | /content/post/\_index.md | site.com/post/ | /layouts/section/post.html | | /content/categories/hugo/\_index.md | site.com/categories/hugo/ | /layouts/taxonomy/hugo.html | +``` ## Why \_index.md files are used @@ -139,7 +143,7 @@ In the above example \_index.md pages have been added to each section/taxonomy. An `_index.md` file has also been added in the top level 'content' directory. -### Where to place \_index.md for the Home page +### Where to place \_index.md for the Homepage Template Hugo themes are designed to use the 'content' directory as the root of the website, so adding an \_index.md file here (like has been done in the example above) is how you would add front matter/content to the home page. @@ -197,363 +201,7 @@ Taxonomy pages will additionally have: **.Data.`Singular`** The taxonomy itself.
-## Example List Template Pages -### Example Section Template: `post.html` - -This content 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" which this example site -defined. - -{{% code file="layouts/section/post.html" %}} -```html -{{ partial "header.html" . }} -{{ partial "subheader.html" . }} - -
-
-

{{ .Title }}

-
    - {{ range .Data.Pages }} - {{ .Render "li"}} - {{ end }} -
-
-
-{{ partial "footer.html" . }} -``` -{{% /code %}} - -### Example Taxonomy Template - -This content template is used for [spf13.com](http://spf13.com/). -It makes use of [partial templates](/templates/partials/). All examples use a -[view](/templates/views/) called either "li" or "summary" which this example site defined. - -{{% code file="layouts/_default/taxonomies.html" download="taxonomies.html" %}} -
-
-

{{ .Title }}

- {{ range .Data.Pages }} - {{ .Render "summary"}} - {{ end }} -
-
-{{ end }} -{{% /code %}} - -## Ordering Content - -In the case of Hugo, each list will render the content based on metadata provided in the [front -matter](/content/front-matter/). See [ordering content](/content/ordering/) for more information. - -Here are a variety of different ways you can order the content items in -your list templates: - -### Order by Weight -> Date (default) - - {{ range .Data.Pages }} -
  • - {{ .Title }} -
    {{ .Date.Format "Mon, Jan 2, 2006" }}
    -
    • - {{ end }} - -### Order by Weight -> Date - - {{ range .Data.Pages.ByWeight }} -
  • - {{ .Title }} -
    {{ .Date.Format "Mon, Jan 2, 2006" }}
    -
    • - {{ end }} - -### Order by Date - - {{ range .Data.Pages.ByDate }} -
  • - {{ .Title }} -
    {{ .Date.Format "Mon, Jan 2, 2006" }}
    -
    • - {{ end }} - -### Order by PublishDate - - {{ range .Data.Pages.ByPublishDate }} -
  • - {{ .Title }} -
    {{ .PublishDate.Format "Mon, Jan 2, 2006" }}
    -
    • - {{ end }} - -### Order by ExpiryDate - - {{ range .Data.Pages.ByExpiryDate }} -
  • - {{ .Title }} -
    {{ .ExpiryDate.Format "Mon, Jan 2, 2006" }}
    -
    • - {{ end }} - -### Order by Lastmod - - {{ range .Data.Pages.ByLastmod }} -
  • - {{ .Title }} -
    {{ .Date.Format "Mon, Jan 2, 2006" }}
    -
    • - {{ end }} - -### Order by Length - - {{ range .Data.Pages.ByLength }} -
  • - {{ .Title }} -
    {{ .Date.Format "Mon, Jan 2, 2006" }}
    -
    • - {{ end }} - - -### Order by Title - - {{ range .Data.Pages.ByTitle }} -
  • - {{ .Title }} -
    {{ .Date.Format "Mon, Jan 2, 2006" }}
    -
    • - {{ end }} - -### Order by LinkTitle - - {{ range .Data.Pages.ByLinkTitle }} -
  • - {{ .LinkTitle }} -
    {{ .Date.Format "Mon, Jan 2, 2006" }}
    -
    • - {{ end }} - -### Order by Parameter - -Order based on the specified front matter parameter. Pages without that -parameter 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.ByParam "rating") }} - - {{ end }} - -If the front matter field of interest is nested beneath another field, you can -also get it: - -``` -{{ range (.Date.Pages.ByParam "author.last_name") }} - -{{ end }} -``` - -### Reverse Order -Can be applied to any of the above. Using Date for an example. - -``` -{{ range .Data.Pages.ByDate.Reverse }} -
  • -{{ .Title }} -
    {{ .Date.Format "Mon, Jan 2, 2006" }}
    -
    • -{{ end }} -``` - -## Grouping Content - -Hugo provides some grouping functions for list pages. You can use them to -group pages by Section, Type, Date etc. - -Here are a variety of different ways you can group the content items in -your list templates: - -### Grouping by Page field - -``` -{{ range .Data.Pages.GroupBy "Section" }} -

    {{ .Key }}

    - -{{ end }} -``` - -### Grouping by Page date - -``` -{{ range .Data.Pages.GroupByDate "2006-01" }} -

    {{ .Key }}

    - -{{ end }} -``` - -### Grouping by Page publish date - -``` -{{ range .Data.Pages.GroupByPublishDate "2006-01" }} -

    {{ .Key }}

    - -{{ end }} -``` - -### Grouping by Page param - -```html -{{ range .Data.Pages.GroupByParam "param_key" }} -

    {{ .Key }}

    - -{{ end }} -``` - -### Grouping by Page param in date format - -```html -{{ range .Data.Pages.GroupByParamDate "param_key" "2006-01" }} -

    {{ .Key }}

    - -{{ end }} -``` - -### 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; they both work the same way, so -it’s really just a matter of preference. - -#### Reverse method - -```golang -{{ range (.Data.Pages.GroupBy "Section").Reverse }} -``` - -```golang -{{ range (.Data.Pages.GroupByDate "2006-01").Reverse }} -``` - - -#### Providing the (alternate) direction - -```golang -{{ range .Data.Pages.GroupByDate "2006-01" "asc" }} -``` - -```golang -{{ range .Data.Pages.GroupBy "Section" "desc" }} -``` - -### Ordering Pages within Group - -Because Grouping returns a key and a slice of pages, all of the ordering methods listed above are available. - -In this example, I’ve ordered the groups in chronological order and the content -within each group in alphabetical order by title. - -```html -{{ range .Data.Pages.GroupByDate "2006-01" "asc" }} -

    {{ .Key }}

    - -{{ end }} -``` - -## Filtering & Limiting Content - -Sometimes you only want to list a subset of the available content. A common -request is to only display “Posts” on the homepage. Using the `where` function, -you can do just that. - -### `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" %}} -```golang -{{ range first 10 .Data.Pages }} - {{ .Render "summary" }} -{{ end }} -``` -{{% /code %}} - -### `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` and `where` Together - -Using `first` and `where` together can be very powerful: - -{{% code file="first-and-where-together.html" %}} -```golang -{{ 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/).) diff --git a/content/templates/ordering-and-grouping-lists.md b/content/templates/ordering-and-grouping-lists.md index 6e4fba731..ac631f4a3 100644 --- a/content/templates/ordering-and-grouping-lists.md +++ b/content/templates/ordering-and-grouping-lists.md @@ -1,6 +1,6 @@ --- title: Ordering and Grouping Lists -linktitle: Ordering and Grouping +linktitle: Rendering Lists description: Hugo assumes that the same structure that works to organize your source content is used to organize the rendered site, but date: 2017-02-01 publishdate: 2017-02-01 @@ -19,3 +19,366 @@ needsreview: true ## Understanding `.Data.*Pages` From this image, we can assume that the "homepage" for Section A---presumably, `/section-a/index.html`---is going to list the content pages 1,2,3. In this way, pages 1,2,3 are *data* made available to the template that renders to the . + +## Example List Template Pages + +### Example Section Template: `post.html` + +This content 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" which this example site defined. + +{{% code file="layouts/section/post.html" %}} +```html +{{ partial "header.html" . }} +{{ partial "subheader.html" . }} + +
    +
    +

    {{ .Title }}

    +
      + {{ range .Data.Pages }} + {{ .Render "li"}} + {{ end }} +
    +
    +
    +{{ partial "footer.html" . }} +``` +{{% /code %}} + +### Example Taxonomy Template + +This content template is used for [spf13.com](http://spf13.com/). It makes use of [partial templates](/templates/partials/). All examples use a [view](/templates/views/) called either "li" or "summary" which this example site defined. + +{{% code file="layouts/_default/taxonomies.html" download="taxonomies.html" %}} +```html +{{ define "main" }} +
    +
    +

    {{ .Title }}

    + {{ range .Data.Pages }} + {{ .Render "summary"}} + {{ end }} +
    +
    +{{ end }} +``` +{{% /code %}} + +## Ordering Content + +In the case of Hugo, each list will render the content based on metadata provided in the [front matter](/content/front-matter/). See [ordering content](/content/ordering/) for more information. + +Here are a variety of different ways you can order the content items in +your list templates: + +### Default Ordering: `Weight > Date` + +{{% code file="layouts/_default/list.html" %}} +```html + +``` +{{% /code %}} + +### Order by Weight -> Date + +```html +{{ range .Data.Pages.ByWeight }} +
  • + {{ .Title }} +
    {{ .Date.Format "Mon, Jan 2, 2006" }}
    +
    • +{{ end }} +``` + +### Order by Date + + {{ range .Data.Pages.ByDate }} +
  • + {{ .Title }} +
    {{ .Date.Format "Mon, Jan 2, 2006" }}
    +
    • + {{ end }} + +### Order by PublishDate + + {{ range .Data.Pages.ByPublishDate }} +
  • + {{ .Title }} +
    {{ .PublishDate.Format "Mon, Jan 2, 2006" }}
    +
    • + {{ end }} + +### Order by ExpiryDate + + {{ range .Data.Pages.ByExpiryDate }} +
  • + {{ .Title }} +
    {{ .ExpiryDate.Format "Mon, Jan 2, 2006" }}
    +
    • + {{ end }} + +### Order by Lastmod + + {{ range .Data.Pages.ByLastmod }} +
  • + {{ .Title }} +
    {{ .Date.Format "Mon, Jan 2, 2006" }}
    +
    • + {{ end }} + +### Order by Length + + {{ range .Data.Pages.ByLength }} +
  • + {{ .Title }} +
    {{ .Date.Format "Mon, Jan 2, 2006" }}
    +
    • + {{ end }} + + +### Order by Title + + {{ range .Data.Pages.ByTitle }} +
  • + {{ .Title }} +
    {{ .Date.Format "Mon, Jan 2, 2006" }}
    +
    • + {{ end }} + +### Order by LinkTitle + + {{ range .Data.Pages.ByLinkTitle }} +
  • + {{ .LinkTitle }} +
    {{ .Date.Format "Mon, Jan 2, 2006" }}
    +
    • + {{ end }} + +### Order by Parameter + +Order based on the specified front matter parameter. Pages without that +parameter 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.ByParam "rating") }} + + {{ end }} + +If the front matter field of interest is nested beneath another field, you can +also get it: + +``` +{{ range (.Date.Pages.ByParam "author.last_name") }} + +{{ end }} +``` + +### Reverse Order +Can be applied to any of the above. Using Date for an example. + +``` +{{ range .Data.Pages.ByDate.Reverse }} +
  • +{{ .Title }} +
    {{ .Date.Format "Mon, Jan 2, 2006" }}
    +
    • +{{ end }} +``` + +## Grouping Content + +Hugo provides some grouping functions for list pages. You can use them to +group pages by Section, Type, Date etc. + +Here are a variety of different ways you can group the content items in +your list templates: + +### Grouping by Page field + +``` +{{ range .Data.Pages.GroupBy "Section" }} +

    {{ .Key }}

    + +{{ end }} +``` + +### Grouping by Page date + +``` +{{ range .Data.Pages.GroupByDate "2006-01" }} +

    {{ .Key }}

    + +{{ end }} +``` + +### Grouping by Page publish date + +``` +{{ range .Data.Pages.GroupByPublishDate "2006-01" }} +

    {{ .Key }}

    + +{{ end }} +``` + +### Grouping by Page param + +```html +{{ range .Data.Pages.GroupByParam "param_key" }} +

    {{ .Key }}

    + +{{ end }} +``` + +### Grouping by Page param in date format + +```html +{{ range .Data.Pages.GroupByParamDate "param_key" "2006-01" }} +

    {{ .Key }}

    + +{{ end }} +``` + +### 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; they both work the same way, so +it’s really just a matter of preference. + +#### Reverse method + +```golang +{{ range (.Data.Pages.GroupBy "Section").Reverse }} +``` + +```golang +{{ range (.Data.Pages.GroupByDate "2006-01").Reverse }} +``` + + +#### Providing the (alternate) direction + +```golang +{{ range .Data.Pages.GroupByDate "2006-01" "asc" }} +``` + +```golang +{{ range .Data.Pages.GroupBy "Section" "desc" }} +``` + +### Ordering Pages within Group + +Because Grouping returns a key and a slice of pages, all of the ordering methods listed above are available. + +In this example, I’ve ordered the groups in chronological order and the content +within each group in alphabetical order by title. + +```html +{{ range .Data.Pages.GroupByDate "2006-01" "asc" }} +

    {{ .Key }}

    + +{{ end }} +``` + +## Filtering & Limiting Content + +Sometimes you only want to list a subset of the available content. A common +request is to only display “Posts” on the homepage. Using the `where` function, +you can do just that. + +### `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" %}} +```golang +{{ range first 10 .Data.Pages }} + {{ .Render "summary" }} +{{ end }} +``` +{{% /code %}} + +### `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` and `where` Together + +Using `first` and `where` together can be very powerful: + +{{% code file="first-and-where-together.html" %}} +```golang +{{ range first 5 (where .Data.Pages "Section" "post") }} + {{ .Content }} +{{ end }} +``` +{{% /code %}}