From bdf3ffc73f77910165ba0f3d7e3f6d4e4e9c2d69 Mon Sep 17 00:00:00 2001 From: Joe Mooring Date: Fri, 23 Aug 2024 07:05:33 -0700 Subject: [PATCH] Clarify the various next/prev methods --- content/en/getting-started/configuration.md | 40 +++++++++- content/en/methods/_common/_index.md | 13 ---- ...next-prev-on-page-vs-next-prev-on-pages.md | 37 --------- content/en/methods/page/Next.md | 40 +--------- content/en/methods/page/NextInSection.md | 60 +------------- content/en/methods/page/Prev.md | 44 +---------- content/en/methods/page/PrevInSection.md | 53 +------------ .../en/methods/page/_common/next-and-prev.md | 60 ++++++++++++++ .../nextinsection-and-previnsection.md | 78 +++++++++++++++++++ content/en/methods/pages/Next.md | 44 +---------- content/en/methods/pages/Prev.md | 44 +---------- .../en/methods/pages/_common/next-and-prev.md | 72 +++++++++++++++++ 12 files changed, 263 insertions(+), 322 deletions(-) delete mode 100644 content/en/methods/_common/_index.md delete mode 100644 content/en/methods/_common/next-prev-on-page-vs-next-prev-on-pages.md create mode 100644 content/en/methods/page/_common/next-and-prev.md create mode 100644 content/en/methods/page/_common/nextinsection-and-previnsection.md create mode 100644 content/en/methods/pages/_common/next-and-prev.md diff --git a/content/en/getting-started/configuration.md b/content/en/getting-started/configuration.md index 924f75f67b..b0a6cae66f 100644 --- 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 deleted file mode 100644 index 4328d4d145..0000000000 --- a/content/en/methods/_common/_index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -cascade: - _build: - list: never - publishResources: false - render: never ---- - - 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 deleted file mode 100644 index f650378784..0000000000 --- a/content/en/methods/_common/next-prev-on-page-vs-next-prev-on-pages.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -# Do not remove front matter. ---- - -The `Next` and `Prev` methods on a `Pages` object are more flexible than the `Next` and `Prev` methods on a `Page` object. - -||Page collection|Custom sort order -:--|:--|:-: -[`PAGES.Next`] and [`PAGES.Prev`]|locally defined|✔️ -[`PAGE.Next`] and [`PAGE.Prev`]|globally defined|❌ - -[`PAGES.Next`]: /methods/pages/next/ -[`PAGES.Prev`]: /methods/pages/prev/ -[`PAGE.Next`]: /methods/page/next/ -[`PAGE.Prev`]: /methods/page/prev/ - -locally defined -: Build the page collection every time you call `PAGES.Next` and `PAGES.Prev`. Navigation between pages is relative to the current page's position within the local collection, independent of the global collection. - -With a local collection, the navigation sort order is the same as the collection sort order. - -globally defined -: Build the page collection once, on a list page. Navigation between pages is relative to the current page's position within the global collection. - -With a global collection, 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 global 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/ diff --git a/content/en/methods/page/Next.md b/content/en/methods/page/Next.md index 57fc1f2f87..ff05257006 100644 --- 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 }} - Prev -{{ end }} - -{{ with .Prev }} - Next -{{ 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 index 59a35d03dc..640e9b44a3 100644 --- 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 }} - Previous in section -{{ end }} - -{{ with .PrevInSection }} - Next in section -{{ 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 index b1a503af53..d28b50265a 100644 --- 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 }} - Prev -{{ end }} - -{{ with .Prev }} - Next -{{ 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 index b96903b4ba..aaafb367ec 100644 --- 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 }} - Previous in section -{{ end }} - -{{ with .PrevInSection }} - Next in section -{{ 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" %}} diff --git a/content/en/methods/page/_common/next-and-prev.md b/content/en/methods/page/_common/next-and-prev.md new file mode 100644 index 0000000000..252e1ad9b5 --- /dev/null +++ b/content/en/methods/page/_common/next-and-prev.md @@ -0,0 +1,60 @@ +--- +# Do not remove front matter. +--- + +Hugo determines the _next_ and _previous_ page by sorting the site's collection of regular pages 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 sorted page collection used to determine the _next_ and _previous_ page is independent of other page collections, which may lead to unexpected behavior. + +For example, 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 +``` + +And these templates: + +{{< code file=layouts/_default/list.html >}} +{{ range .Pages.ByWeight}} +

{{ .LinkTitle }}

+{{ end }} +{{< /code >}} + +{{< code file=layouts/_default/single.html >}} +{{ with .Prev }} + Previous +{{ end }} + +{{ with .Next }} + Next +{{ end }} +{{< /code >}} + +When you visit page-2: + +- The `Prev` method points to page-3 +- The `Next` method points to page-1 + +To reverse the meaning of _next_ and _previous_ you can change the sort direction in your [site configuration], or use the [`Next`] and [`Prev`] methods on a `Pages` object for more flexibility. + +[site configuration]: getting-started/configuration/#configure-page +[`Next`]: /methods/pages/prev +[`Prev`]: /methods/pages/prev diff --git a/content/en/methods/page/_common/nextinsection-and-previnsection.md b/content/en/methods/page/_common/nextinsection-and-previnsection.md new file mode 100644 index 0000000000..aed9a310f6 --- /dev/null +++ b/content/en/methods/page/_common/nextinsection-and-previnsection.md @@ -0,0 +1,78 @@ +--- +# Do not remove front matter. +--- + +Hugo determines the _next_ and _previous_ page by sorting the current section's regular pages 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 sorted page collection used to determine the _next_ and _previous_ page is independent of other page collections, which may lead to unexpected behavior. + +For example, 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 +``` + +And these templates: + +{{< code file=layouts/_default/list.html >}} +{{ range .Pages.ByWeight}} +

{{ .LinkTitle }}

+{{ end }} +{{< /code >}} + +{{< code file=layouts/_default/single.html >}} +{{ with .PrevInSection }} + Previous +{{ end }} + +{{ with .NextInSection }} + Next +{{ end }} +{{< /code >}} + +When you visit page-2: + +- The `PrevInSection` method points to page-3 +- The `NextInSection` method points to page-1 + +To reverse the meaning of _next_ and _previous_ you can change the sort direction in your [site configuration], or use the [`Next`] and [`Prev`] methods on a `Pages` object for more flexibility. + +[site configuration]: getting-started/configuration/#configure-page +[`Next`]: /methods/pages/prev +[`Prev`]: /methods/pages/prev + +## Example + +Code defensively by checking for page existence: + +```go-html-template +{{ with .PrevInSection }} + Previous +{{ end }} + +{{ with .NextInSection }} + Next +{{ end }} +``` + +## Alternative + +Use the [`Next`] and [`Prev`] methods on a `Pages` object for more flexibility. diff --git a/content/en/methods/pages/Next.md b/content/en/methods/pages/Next.md index b7284609fd..dcf1231ac7 100644 --- a/content/en/methods/pages/Next.md +++ b/content/en/methods/pages/Next.md @@ -1,55 +1,17 @@ --- title: Next -description: Returns the next page in a local page collection, relative to the given page. +description: Returns the next page in a page collection, relative to the given page. categories: [] keywords: [] action: related: - methods/pages/Prev - methods/page/Next - - methods/page/NextInSection - methods/page/Prev + - methods/page/NextInSection - methods/page/PrevInSection returnType: page.Page signatures: [PAGES.Next PAGE] -toc: true --- -The behavior of the `Prev` and `Next` methods on a `Pages` objects is probably the reverse of what you expect. - -With this content structure and the page collection sorted by weight in ascending order: - -```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 -{{ $pages := where .Site.RegularPages.ByWeight "Section" "pages" }} - -{{ with $pages.Next . }} - Previous -{{ end }} - -{{ with $pages.Prev . }} - Next -{{ end }} -``` - -## Compare to Page methods - -{{% include "methods/_common/next-prev-on-page-vs-next-prev-on-pages.md" %}} +{{% include "methods/pages/_common/next-and-prev.md" %}} diff --git a/content/en/methods/pages/Prev.md b/content/en/methods/pages/Prev.md index b9ef27a458..2d87385217 100644 --- a/content/en/methods/pages/Prev.md +++ b/content/en/methods/pages/Prev.md @@ -1,55 +1,17 @@ --- title: Prev -description: Returns the previous page in a local page collection, relative to the given page. +description: Returns the previous page in a page collection, relative to the given page. categories: [] keywords: [] action: related: - methods/pages/Next - methods/page/Next - - methods/page/NextInSection - methods/page/Prev + - methods/page/NextInSection - methods/page/PrevInSection returnType: page.Pages signatures: [PAGES.Prev PAGE] -toc: true --- -The behavior of the `Prev` and `Next` methods on a `Pages` objects is probably the reverse of what you expect. - -With this content structure and the page collection sorted by weight in ascending order: - -```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 -{{ $pages := where .Site.RegularPages.ByWeight "Section" "pages" }} - -{{ with $pages.Next . }} - Previous -{{ end }} - -{{ with $pages.Prev . }} - Next -{{ end }} -``` - -## Compare to Page methods - -{{% include "methods/_common/next-prev-on-page-vs-next-prev-on-pages.md" %}} +{{% include "methods/pages/_common/next-and-prev.md" %}} diff --git a/content/en/methods/pages/_common/next-and-prev.md b/content/en/methods/pages/_common/next-and-prev.md new file mode 100644 index 0000000000..e0d05de845 --- /dev/null +++ b/content/en/methods/pages/_common/next-and-prev.md @@ -0,0 +1,72 @@ +--- +# Do not remove front matter. +--- + +Hugo determines the _next_ and _previous_ page by sorting the 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 sorted page collection used to determine the _next_ and _previous_ page is independent of other page collections, which may lead to unexpected behavior. + +For example, 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 +``` + +And these templates: + +{{< code file=layouts/_default/list.html >}} +{{ range .Pages.ByWeight}} +

{{ .LinkTitle }}

+{{ end }} +{{< /code >}} + +{{< code file=layouts/_default/single.html >}} +{{ $pages := .CurrentSection.Pages.ByWeight }} + +{{ with $pages.Prev . }} + Previous +{{ end }} + +{{ with $pages.Next . }} + Next +{{ end }} +{{< /code >}} + +When you visit page-2: + +- The `Prev` method points to page-3 +- The `Next` method points to page-1 + +To reverse the meaning of _next_ and _previous_ you can chain the [`Reverse`] method to the page collection definition: + +{{< code file=layouts/_default/single.html >}} +{{ $pages := .CurrentSection.Pages.ByWeight.Reverse }} + +{{ with $pages.Prev . }} + Previous +{{ end }} + +{{ with $pages.Next . }} + Next +{{ end }} +{{< /code >}} + +[`Reverse`]: /methods/pages/reverse/