Clarify the meaning of .Pages vs .Site.Pages

Fixes https://github.com/gohugoio/hugoDocs/issues/398.

content/en/readfiles/pages-vs-site-pages.md

@@ -0,0 +1,9 @@
+| Variable             | Current context | Pages included                                                                                                                                                                                           |
+|----------------------|-----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `.Site.Pages`        | **any** page    | ALL pages of the site: content, sections, taxonomies, etc. -- Superset of everything!                                                                                                                     |
+| `.Site.RegularPages` | **any** page    | Only regular (content) pages -- Subset of `.Site.Pages`                                                                                                                                                   |
+| `.Pages`             | _List_ page     | Regular pages under that _list_ page representing the homepage, section, taxonomy term (`/tags`) or taxonomy (`/tags/foo`) page -- Subset of `.Site.Pages` or `.Site.RegularPages`, depending on context. |
+| `.Pages`             | _Single_ page   | empty slice                                                                                                                                                                                              |
+
+Note
+: In the **home** context (`index.html`), `.Pages` is the same as `.Site.RegularPages`.

content/en/variables/page.md

@@ -106,9 +106,8 @@ See also `.ExpiryDate`, `.Date`, `.PublishDate`, and [`.GitInfo`][gitinfo].
 : contains all formats, including the current format, for a given page. Can be combined the with [`.Get` function](/functions/get/) to grab a specific format. (See [Output Formats](/templates/output-formats/).)
 
 .Pages
-: a collection of associated pages. `.Pages` is an alias for
+: a collection of associated pages. This value will be `nil` within
-  `.Data.Pages`. This value will be `nil` within the context of
+  the context of regular content pages. See [`.Pages`](#pages).
-  regular content pages.
 
 .Permalink
 : the Permanent link for this page; see [Permalinks](/content-management/urls/)
@@ -187,6 +186,15 @@ Also see [Sections](/content-management/sections/).
 
 {{< readfile file="/content/en/readfiles/sectionvars.md" markdown="true" >}}
 
+## The `.Pages` Variable {#pages}
+
+`.Pages` is an alias to `.Data.Pages`. It is conventional to use the
+aliased form `.Pages`.
+
+### `.Pages` compared to `.Site.Pages`
+
+{{< readfile file="/content/en/readfiles/pages-vs-site-pages.md" markdown="true" >}}
+
 ## Page-level Params
 
 Any other value defined in the front matter in a content file, including taxonomies, will be made available as part of the `.Params` variable.

content/en/variables/site.md

@@ -83,13 +83,13 @@ The following is a list of site-level (aka "global") variables. Many of these va
 : all of the menus in the site.
 
 .Site.Pages
-: array of all content ordered by Date with the newest first. This array contains only the pages in the current language.
+: array of all content ordered by Date with the newest first. This array contains only the pages in the current language. See [`.Site.Pages`](#site-pages).
 
 .Site.Permalinks
 : a string to override the default [permalink](/content-management/urls/) format as defined in the site configuration.
 
 .Site.RegularPages
-: a shortcut to the *regular* page collection. `.Site.RegularPages` is equivalent to `where .Site.Pages "Kind" "page"`.
+: a shortcut to the *regular* page collection. `.Site.RegularPages` is equivalent to `where .Site.Pages "Kind" "page"`. See [`.Site.Pages`](#site-pages).
 
 .Site.RSSLink
 : the URL for the site RSS.
@@ -125,4 +125,13 @@ You can use `.Site.Params` in a [partial template](/templates/partials/) to call
 <meta name="description" content="{{if .IsHome}}{{ $.Site.Params.description }}{{else}}{{.Description}}{{end}}" />
 {{< /code >}}
 
+## The `.Site.Pages` Variable {#site-pages}
+
+### `.Site.Pages` compared to `.Pages`
+
+{{< readfile file="/content/en/readfiles/pages-vs-site-pages.md" markdown="true" >}}
+
+
+
+
 [config]: /getting-started/configuration/