Clarify the various next/prev methods

gohugoio · Aug 23, 2024 · bdf3ffc · bdf3ffc
1 parent b5505d2
commit bdf3ffc
Show file tree

Hide file tree

Showing 12 changed files with 263 additions and 322 deletions.
diff --git a/content/en/getting-started/configuration.md b/content/en/getting-started/configuration.md
@@ -380,7 +380,7 @@ See [custom output formats].
 
 ###### page
 
-See [Page Configuration](#configure-page).
+See [configure page](#configure-page).
 
 ###### pagination
 
@@ -504,11 +504,45 @@ enableemoji: true
 
 {{< new-in 0.133.0 >}}
 
-The `page` configuration section contains [page]-related configuration options.
+These methods on a `Page` object navigate to the next or previous page within a page collection, relative to the current page:
+
+- [Next](/methods/page/next/)
+- [NextInSection](/methods/page/nextinsection/)
+- [Prev](/methods/page/prev/)
+- [PrevInSection](/methods/page/previnsection/)
+
+Hugo determines the _next_ and _previous_ page by sorting a page collection according to this sorting hierarchy:
+
+Field|Precedence|Sort direction
+:--|:--|:--
+[`weight`]|1|descending
+[`date`]|2|descending
+[`linkTitle`]|3|descending
+[`path`]|4|descending
+
+[`date`]: /methods/page/date/
+[`weight`]: /methods/page/weight/
+[`linkTitle`]: /methods/page/linktitle/
+[`path`]: /methods/page/path/
+
+The sort direction in the table above corresponds to these default site configuration values:
 
 {{< code-toggle config=page />}}
 
-[page]:/methods/page/
+To sort all fields in ascending order:
+
+{{< code-toggle file=hugo >}}
+[page]
+  nextPrevInSectionSortOrder = 'asc'
+  nextPrevSortOrder = 'asc'
+{{< /code-toggle >}}
+
+{{% note %}}
+These settings do not apply to the [`Next`] or [`Prev`] methods on a `Pages` object.
+
+[`Next`]: /methods/pages/next
+[`Prev`]: /methods/pages/next
+{{% /note %}}
 
 ## Configure build
 

diff --git a/content/en/methods/_common/_index.md b/content/en/methods/_common/_index.md
diff --git a/content/en/methods/_common/next-prev-on-page-vs-next-prev-on-pages.md b/content/en/methods/_common/next-prev-on-page-vs-next-prev-on-pages.md
diff --git a/content/en/methods/page/Next.md b/content/en/methods/page/Next.md
@@ -1,6 +1,6 @@
 ---
 title: Next
-description: Returns the next page in a global page collection, relative to the given page. 
+description: Returns the next page in a site's collection of regular pages, relative to the current page.
 categories: []
 keywords: []
 action:
@@ -12,42 +12,6 @@ action:
     - methods/pages/Prev
   returnType: page.Page
   signatures: [PAGE.Next]
-toc: true
 ---
 
-The behavior of the `Prev` and `Next` methods on a `Page` object is probably the reverse of what you expect.
-
-With this content structure:
-
-```text
-content/
-├── pages/
-│   ├── _index.md
-│   ├── page-1.md   <-- front matter: weight = 10
-│   ├── page-2.md   <-- front matter: weight = 20
-│   └── page-3.md   <-- front matter: weight = 30
-└── _index.md
-```
-
-When you visit page-2:
-
-- The `Prev` method points to page-3
-- The `Next` method points to page-1
-
-{{% note %}}
-Use the opposite label in your navigation links as shown in the example below.
-{{% /note %}}
-
-```go-html-template
-{{ with .Next }}
-  <a href="{{ .RelPermalink }}">Prev</a>
-{{ end }}
-
-{{ with .Prev }}
-  <a href="{{ .RelPermalink }}">Next</a>
-{{ end }}
-```
-
-## Compare to Pages methods
-
-{{% include "methods/_common/next-prev-on-page-vs-next-prev-on-pages.md" %}}
+{{% include "methods/page/_common/next-and-prev.md" %}}
diff --git a/content/en/methods/page/NextInSection.md b/content/en/methods/page/NextInSection.md
@@ -1,71 +1,15 @@
 ---
 title: NextInSection
-description: Returns the next page within a section, relative to the given page. 
+description: Returns the next regular page in a section, relative to the given page. 
 categories: []
 keywords: []
 action:
   related:
     - methods/page/PrevInSection
-    - methods/page/Next
-    - methods/page/Prev
     - methods/pages/Next
     - methods/pages/Prev
   returnType: page.Page
   signatures: [PAGE.NextInSection]
 ---
 
-The behavior of the `PrevInSection` and `NextInSection` methods on a `Page` object is probably the reverse of what you expect.
-
-With this content structure:
-
-```text
-content/
-├── books/
-│   ├── _index.md
-│   ├── book-1.md
-│   ├── book-2.md
-│   └── book-3.md
-├── films/
-│   ├── _index.md
-│   ├── film-1.md
-│   ├── film-2.md
-│   └── film-3.md
-└── _index.md
-```
-
-When you visit book-2:
-
-- The `PrevInSection` method points to book-3
-- The `NextInSection` method points to book-1
-
-{{% note %}}
-Use the opposite label in your navigation links as shown in the example below.
-{{% /note %}}
-
-```go-html-template
-{{ with .NextInSection }}
-  <a href="{{ .RelPermalink }}">Previous in section</a>
-{{ end }}
-
-{{ with .PrevInSection }}
-  <a href="{{ .RelPermalink }}">Next in section</a>
-{{ end }}
-```
-
-{{% note %}}
-The navigation sort order may be different than the page collection sort order.
-{{% /note %}}
-
-With the `PrevInSection` and `NextInSection` methods, the navigation sort order is fixed, using Hugo’s default sort order. In order of precedence:
-
-1. Page [weight]
-2. Page [date] (descending)
-3. Page [linkTitle], falling back to page [title]
-4. Page file path if the page is backed by a file
-
-For example, with a page collection sorted by title, the navigation sort order will use Hugo’s default sort order. This is probably not what you want or expect. For this reason, the Next and Prev methods on a Pages object are generally a better choice.
-
-[date]: /methods/page/date/
-[weight]: /methods/page/weight/
-[linkTitle]: /methods/page/linktitle/
-[title]: /methods/page/title/
+{{% include "methods/page/_common/nextinsection-and-previnsection.md" %}}
diff --git a/content/en/methods/page/Prev.md b/content/en/methods/page/Prev.md
@@ -1,53 +1,17 @@
 ---
 title: Prev
-description: Returns the previous page in a global page collection, relative to the given page. 
+description: Returns the previous page in a site's collection of regular pages, relative to the current page.
 categories: []
 keywords: []
 action:
   related:
     - methods/page/Next
-    - methods/page/PrevInSection
     - methods/page/NextInSection
-    - methods/pages/Prev
+    - methods/page/PrevInSection
     - methods/pages/Next
+    - methods/pages/Prev
   returnType: page.Page
   signatures: [PAGE.Prev]
-toc: true
 ---
 
-The behavior of the `Prev` and `Next` methods on a `Page` object is probably the reverse of what you expect.
-
-With this content structure:
-
-```text
-content/
-├── pages/
-│   ├── _index.md
-│   ├── page-1.md   <-- front matter: weight = 10
-│   ├── page-2.md   <-- front matter: weight = 20
-│   └── page-3.md   <-- front matter: weight = 30
-└── _index.md
-```
-
-When you visit page-2:
-
-- The `Prev` method points to page-3
-- The `Next` method points to page-1
-
-{{% note %}}
-Use the opposite label in your navigation links as shown in the example below.
-{{% /note %}}
-
-```go-html-template
-{{ with .Next }}
-  <a href="{{ .RelPermalink }}">Prev</a>
-{{ end }}
-
-{{ with .Prev }}
-  <a href="{{ .RelPermalink }}">Next</a>
-{{ end }}
-```
-
-## Compare to Pages methods
-
-{{% include "methods/_common/next-prev-on-page-vs-next-prev-on-pages.md" %}}
+{{% include "methods/page/_common/next-and-prev.md" %}}
diff --git a/content/en/methods/page/PrevInSection.md b/content/en/methods/page/PrevInSection.md
@@ -1,64 +1,15 @@
 ---
 title: PrevInSection
-description: Returns the previous page within a section, relative to the given page.  
+description: Returns the previous regular page in a section, relative to the given page. 
 categories: []
 keywords: []
 action:
   related:
     - methods/page/NextInSection
-    - methods/page/Next
     - methods/pages/Next
-    - methods/page/Prev
     - methods/pages/Prev
   returnType: page.Page
   signatures: [PAGE.PrevInSection]
 ---
 
-
-The behavior of the `PrevInSection` and `NextInSection` methods on a `Page` object is probably the reverse of what you expect.
-
-With this content structure:
-
-```text
-content/
-├── books/
-│   ├── _index.md
-│   ├── book-1.md
-│   ├── book-2.md
-│   └── book-3.md
-├── films/
-│   ├── _index.md
-│   ├── film-1.md
-│   ├── film-2.md
-│   └── film-3.md
-└── _index.md
-```
-
-When you visit book-2:
-
-- The `PrevInSection` method points to book-3
-- The `NextInSection` method points to book-1
-
-{{% note %}}
-Use the opposite label in your navigation links as shown in the example below.
-{{% /note %}}
-
-```go-html-template
-{{ with .NextInSection }}
-  <a href="{{ .RelPermalink }}">Previous in section</a>
-{{ end }}
-
-{{ with .PrevInSection }}
-  <a href="{{ .RelPermalink }}">Next in section</a>
-{{ end }}
-```
-
-
-The `PrevInSection` and `NextInSection` methods uses the default page sort. You can change the sort direction in [Page Config](getting-started/configuration/#configure-page). For more flexibility, use the [Next] and [Prev] methods on the Page object.
-
-[date]: /methods/page/date/
-[weight]: /methods/page/weight/
-[linkTitle]: /methods/page/linktitle/
-[title]: /methods/page/title/
-[Next]: /methods/page/next/
-[Prev]: /methods/page/prev/
+{{% include "methods/page/_common/nextinsection-and-previnsection.md" %}}