From 466ff96c5c7d388f6b95dd93097455d17d521fca Mon Sep 17 00:00:00 2001 From: Kaushal Modi Date: Fri, 9 Mar 2018 15:53:06 -0500 Subject: [PATCH] Update Output Formats and Page Kinds documentation Fixes https://github.com/gohugoio/hugoDocs/issues/401, https://github.com/gohugoio/hugoDocs/issues/402 --- content/templates/output-formats.md | 39 ++++++++++++++++++------ content/templates/section-templates.md | 42 ++++++++++++++++++-------- 2 files changed, 59 insertions(+), 22 deletions(-) diff --git a/content/templates/output-formats.md b/content/templates/output-formats.md index 9af68f5e04e..5a44a726923 100644 --- a/content/templates/output-formats.md +++ b/content/templates/output-formats.md @@ -1,7 +1,7 @@ --- title: Custom Output Formats linktitle: Custom Output Formats -description: Hugo can output content in multiple formats, including calendar events, e-book formats, Google AMP, and JSON search indexes, or any custom text format. +description: Hugo can output content in multiple formats, including calendar events, e-book formats, Google AMP, and JSON search indexes, or any custom text format. date: 2017-03-22 publishdate: 2017-03-22 lastmod: 2017-03-22 @@ -60,11 +60,11 @@ suffix = "htm" mediaType = "text/html" ``` -**Note** that for the above to work, you also need to add an`outputs` definition in your site config. +**Note** that for the above to work, you also need to add an `outputs` definition in your site config. -## Output Formats +## Output Format Definitions -Given a media type and some additional configuration, you get an `Output Format`: +Given a media type and some additional configuration, you get an **Output Format**. This is the full set of Hugo's built-in output formats: @@ -122,9 +122,20 @@ The following is the full list of configuration options for output formats and t ## Output Formats for Pages -A `Page` in Hugo can be rendered to multiple representations on the file system. By default, all pages will render as `HTML` with some of them also as `RSS` (homepage, sections, etc.). +A `Page` in Hugo can be rendered to multiple *output formats* on the file +system. -This can be changed by defining an `outputs` list of output formats in either the `Page` front matter or in the site configuration (either for all sites or per language). +### Default Output Formats +By default, **all** pages will render to `HTML`. + +Every `Page` also has a [`Kind`][page kinds] attribute. By default, all pages +other than the `page` `Kind` will also render to the `RSS` output format. + +### Customizing Output Formats + +This can be changed by defining an `outputs` list of output formats in either +the `Page` front matter or in the site configuration (either for all sites or +per language). Example from site `config.toml`: @@ -142,12 +153,19 @@ outputs: page: ["HTML"] ``` +In the above examples, the *output formats* for `section`, `taxonomyTerm` and +`taxonomy` will be implicitly set to `["HTML"]`. + +{{% note %}} +If you add an `outputs` config section, you replace the Hugo default `outputs` +configuration with your own and must provide a complete configuration. You will +get the `HTML` output for any missing page `Kind` entry. +{{% /note %}} -* The output definition is per `Page` `Kind` (i.e, `page`, `home`, `section`, `taxonomy`, or `taxonomyTerm`). -* The names used must match the `Name` of a defined `Output Format`. -* Any `Kind` without a definition will default to `HTML`. +* The `outputs` definition is per [`Page` `Kind`][page kinds] (i.e, `page`, `home`, `section`, `taxonomy`, or `taxonomyTerm`). +* The names (e.g. `HTML`, `AMP`) used must match the `Name` of a defined *Output Format*. + * These names are case insensitive. * These can be overridden per `Page` in the front matter of content files. -* Output formats are case insensitive. The following is an example of `YAML` front matter in a content file that defines output formats for the rendered `Page`: @@ -222,3 +240,4 @@ The partial below is a plain text template (Outpuf Format is `CSV`, and since th [lookup order]: /templates/lookup/ [media type]: https://en.wikipedia.org/wiki/Media_type [partials]: /templates/partials/ +[page kinds]: /templates/section-templates/#page-kinds diff --git a/content/templates/section-templates.md b/content/templates/section-templates.md index 60e486ecd9d..03b68e51b4c 100644 --- a/content/templates/section-templates.md +++ b/content/templates/section-templates.md @@ -26,25 +26,42 @@ To effectively leverage section page templates, you should first understand Hugo See [Template Lookup](/templates/lookup-order/). -## `.Site.GetPage` with Sections +## Page Kinds -Every `Page` in Hugo has a `.Kind` attribute. `Kind` can easily be combined with the [`where` function][where] in your templates to create kind-specific lists of content. This method is ideal for creating lists, but there are times where you may want to fetch just the index page of a single section via the section's path. +Every `Page` in Hugo has a `.Kind` attribute. It can have one of these values: -The [`.GetPage` function][getpage] looks up an index page of a given `Kind` and `path`. +home +: The home page (e.g. `/index.html`) + +page +: Any content page with a `single` layout. Call it an *entry* of the sake of + current explanation. (e.g. `/posts/my-post/index.html`) + +section +: A page listing entries in a given + [/section/][sections]. (e.g. `/posts/index.html`) + +taxonomy +: A page listing entries from a given *taxonomy*, like `/tags/foo` or + `/categories/bar`. (e.g. `/tags/awesome/index.html`) -{{% note %}} -`.GetPage` is not currently supported to grab single content files but *may* be supported in the future. -{{% /note %}} +taxonomyTerm +: A page listing all *taxonomies* under a *taxonomy term*, like `tags` or + `categories`. (e.g. `/tags/index.html`) -You can call `.Site.GetPage` with two arguments: `kind` and `kind value`. +## `.Site.GetPage` with Sections + +`Kind` can easily be combined with the [`where` function][where] in your templates to create kind-specific lists of content. This method is ideal for creating lists, but there are times where you may want to fetch just the index page of a single section via the section's path. + +The [`.GetPage` function][getpage] looks up an index page of a given `Kind` and `path`. -These are the valid values for 'kind': +You can call `.Site.GetPage` with two arguments: `kind` (one of the valid values +of `Kind` from above) and `kind value`. -1. `home` -2. `section` -3. `taxonomy` -4. `taxonomyTerm` +Examples: +- `{{ .Site.GetPage "section" "posts" }}` +- `{{ .Site.GetPage "page" "search" }}` ## Example: Creating a Default Section Template @@ -113,3 +130,4 @@ Which then returns the following: [lists]: /templates/lists/ [lookup]: /templates/lookup-order/ [where]: /functions/where/ +[sections]: /content-management/sections/