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

diff --git a/docs/content/en/variables/page.md b/docs/content/en/variables/page.md
index 7be94a67ba6b76f6e7a9df366a25fe5a50880997..95c75dec8787dd18efb1d9a4e6c812d4b595f405 100644 (file)
--- a/docs/content/en/variables/page.md
+++ b/docs/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`.

diff --git a/hugolib/hugo_sites_build_test.go b/hugolib/hugo_sites_build_test.go
index 4c32fa2f6169d7bfa84131d947cfe889fe533dfa..63e9e52e69e4720406b917eb104fe94d7d5d235f 100644 (file)
--- a/hugolib/hugo_sites_build_test.go
+++ b/hugolib/hugo_sites_build_test.go
@@ -268,7 +268,7 @@ func doTestMultiSitesBuild(t *testing.T, configTemplate, configSuffix string) {
 
        require.Equal(t, "/superbob", doc3.URL(), "invalid url, was specified on doc3")
        b.AssertFileContent("public/superbob/index.html", "doc3|Hello|en")
-       require.Equal(t, doc2.Next, doc3, "doc3 should follow doc2, in .Next")
+       require.Equal(t, doc2.PrevPage, doc3, "doc3 should follow doc2, in .PrevPage")
 
        doc1fr := doc1en.Translations()[0]
        permalink = doc1fr.Permalink()
@@ -398,16 +398,16 @@ func doTestMultiSitesBuild(t *testing.T, configTemplate, configSuffix string) {
        require.Equal(t, template.URL(""), enSite.RegularPages[0].RSSLink())
 
        // Issue #3108
-       next := enSite.RegularPages[0].Next
-       require.NotNil(t, next)
-       require.Equal(t, KindPage, next.Kind)
+       prevPage := enSite.RegularPages[0].PrevPage
+       require.NotNil(t, prevPage)
+       require.Equal(t, KindPage, prevPage.Kind)
 
        for {
-               if next == nil {
+               if prevPage == nil {
                        break
                }
-               require.Equal(t, KindPage, next.Kind)
-               next = next.Next
+               require.Equal(t, KindPage, prevPage.Kind)
+               prevPage = prevPage.PrevPage
        }
 
        // Check bundles

diff --git a/hugolib/page.go b/hugolib/page.go
index bb6dab8e04a14d070fc35976854ba1959bc40347..8e9e0a7ce09f1194cdaa5468fd8eb34daf1455ff 100644 (file)
--- a/hugolib/page.go
+++ b/hugolib/page.go
@@ -505,8 +505,8 @@ type PageMeta struct {
 }
 
 type Position struct {
-       Prev          *Page
-       Next          *Page
+       PrevPage      *Page
+       NextPage      *Page
        PrevInSection *Page
        NextInSection *Page
 }
@@ -2308,3 +2308,15 @@ func (p *Page) pathOrTitle() string {
        }
        return p.title
 }
+
+func (p *Page) Next() *Page {
+       // TODO Remove in Hugo 0.52
+       helpers.Deprecated("Page", ".Next", "Use .PrevPage (yes, not .NextPage).", false)
+       return p.PrevPage
+}
+
+func (p *Page) Prev() *Page {
+       // TODO Remove in Hugo 0.52
+       helpers.Deprecated("Page", ".Prev", "Use .NextPage (yes, not .PrevPage).", false)
+       return p.NextPage
+}

diff --git a/hugolib/site.go b/hugolib/site.go
index 0eb4d7dfed01cc7f7ddffc0cd2b6475eecaf8c24..054656f7a1f4bebb845b42a0abb1956c5199028d 100644 (file)
--- a/hugolib/site.go
+++ b/hugolib/site.go
@@ -990,12 +990,12 @@ func (s *Site) setupSitePages() {
        var siteLastChange time.Time
 
        for i, page := range s.RegularPages {
-               if i < len(s.RegularPages)-1 {
-                       page.Next = s.RegularPages[i+1]
+               if i > 0 {
+                       page.NextPage = s.RegularPages[i-1]
                }
 
-               if i > 0 {
-                       page.Prev = s.RegularPages[i-1]
+               if i < len(s.RegularPages)-1 {
+                       page.PrevPage = s.RegularPages[i+1]
                }
 
                // Determine Site.Info.LastChange