Update Output Formats and Page Kinds documentation

Fixes gohugoio#401, gohugoio#402

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

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/