From d758ef94a7060477d553471d32d89e593b39ae9c Mon Sep 17 00:00:00 2001
From: Ricardo N Feliciano <FelicianoTech@gmail.com>
Date: Mon, 24 Sep 2018 18:06:29 -0400
Subject: [PATCH] hugolib: Introduce Page.NextPage and Page.PrevPage

Introduce new page position variables in order to fix the ordering issue
of `.Next` and `.Prev` while also allowing an upgrade path via
deprecation.

`.NextInSection` becomes `.NextPageInSection`.
`.PrevInSection` becomes `.PrevPageInSection`.

`.Next` becomes a function returning `.PrevPage`.
`.Prev` becomes a function returning `.NextPage`.

Fixes #1061
---
 content/en/variables/page.md | 18 ++++++++++++------
 1 file changed, 12 insertions(+), 6 deletions(-)

diff --git a/content/en/variables/page.md b/content/en/variables/page.md
index 7be94a67b..95c75dec8 100644
--- a/content/en/variables/page.md
+++ b/content/en/variables/page.md
@@ -96,11 +96,14 @@ See also `.ExpiryDate`, `.Date`, `.PublishDate`, and [`.GitInfo`][gitinfo].
 .LinkTitle
 : access when creating links to the content. If set, Hugo will use the `linktitle` from the front matter before `title`.
 
-.Next
-: pointer to the following content (based on the `publishdate` field in front matter).
+.Next (deprecated)
+: In older Hugo versions this pointer went the wrong direction. Please use `.PrevPage` instead.
+
+.NextPage
+: Pointer to the next [regular page](/variables/site/#site-pages) (sorted by Hugo's [default sort](/templates/lists#default-weight-date-linktitle-filepath)). Example: `{{if .NextPage}}{{.NextPage.Permalink}}{{end}}`.
 
 .NextInSection
-: pointer to the following content within the same section (based on `publishdate` field in front matter).
+: Pointer to the next [regular page](/variables/site/#site-pages) within the same section. Pages are sorted by Hugo's [default sort](/templates/lists#default-weight-date-linktitle-filepath). Example: `{{if .NextInSection}}{{.NextInSection.Permalink}}{{end}}`.
 
 .OutputFormats
 : 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/).)
@@ -118,11 +121,14 @@ See also `.ExpiryDate`, `.Date`, `.PublishDate`, and [`.GitInfo`][gitinfo].
 .PlainWords
 : the Page content stripped of HTML as a `[]string` using Go's [`strings.Fields`](https://golang.org/pkg/strings/#Fields) to split `.Plain` into a slice.
 
-.Prev
-: Pointer to the previous content (based on `publishdate` in front matter).
+.Prev (deprecated)
+: In older Hugo versions this pointer went the wrong direction. Please use `.NextPage` instead.
+
+.PrevPage
+: Pointer to the previous [regular page](/variables/site/#site-pages) (sorted by Hugo's [default sort](/templates/lists#default-weight-date-linktitle-filepath)). Example: `{{if .PrevPage}}{{.PrevPage.Permalink}}{{end}}`.
 
 .PrevInSection
-: Pointer to the previous content within the same section (based on `publishdate` in front matter). For example, `{{if .PrevInSection}}{{.PrevInSection.Permalink}}{{end}}`.
+: Pointer to the previous [regular page](/variables/site/#site-pages) within the same section. Pages are sorted by Hugo's [default sort](/templates/lists#default-weight-date-linktitle-filepath). Example: `{{if .PrevInSection}}{{.PrevInSection.Permalink}}{{end}}`.
 
 .PublishDate
 : the date on which the content was or will be published; `.Publishdate` pulls from the `publishdate` field in a content's front matter. See also `.ExpiryDate`, `.Date`, and `.Lastmod`.