Document new pagination config

gohugoio · Jun 25, 2024 · 4449d53 · 4449d53
1 parent 0af8be4
commit 4449d53
Show file tree

Hide file tree

Showing 16 changed files with 311 additions and 127 deletions.
diff --git a/.cspell.json b/.cspell.json
@@ -71,6 +71,7 @@
     "attrlink",
     "canonify",
     "codeowners",
+    "dynacache",
     "eturl",
     "getenv",
     "gohugo",
@@ -89,6 +90,7 @@
     "# cspell: ignore foreign language words",
     "# ----------------------------------------------------------------------",
     "bezpieczeństwo",
+    "blatt",
     "buch",
     "descripción",
     "dokumentation",

diff --git a/content/en/functions/collections/Group.md b/content/en/functions/collections/Group.md
@@ -28,4 +28,4 @@ aliases: [/functions/group]
 {{ end }}
 ```
 
-The page group you get from `group` is of the same type you get from the built-in [group methods](/templates/lists#group-content) in Hugo. The above example can be [paginated](/templates/pagination/#list-paginator-pages).
+The page group you get from `group` is of the same type you get from the built-in [group methods](/templates/lists#group-content) in Hugo. The example above can be [paginated](/templates/pagination/).
diff --git a/content/en/functions/data/GetCSV.md b/content/en/functions/data/GetCSV.md
@@ -13,6 +13,7 @@ action:
   returnType: '[][]string'
   signatures: ['data.GetCSV SEPARATOR INPUT... [OPTIONS]']
 toc: true
+expiryDate: 2025-02-19 # deprecated 2024-02-19
 ---
 
 {{% deprecated-in 0.123.0 %}}

diff --git a/content/en/functions/data/GetJSON.md b/content/en/functions/data/GetJSON.md
@@ -13,6 +13,7 @@ action:
   returnType: any
   signatures: ['data.GetJSON INPUT... [OPTIONS]']
 toc: true
+expiryDate: 2025-02-19 # deprecated 2024-02-19
 ---
 
 {{% deprecated-in 0.123.0 %}}

diff --git a/content/en/getting-started/configuration.md b/content/en/getting-started/configuration.md
@@ -378,13 +378,9 @@ Module configuration see [module configuration](/hugo-modules/configuration/).
 
 See [custom output formats].
 
-###### paginate
+###### pagination
 
-(`int`) Default number of elements per page in [pagination](/templates/pagination/). Default is `10`.
-
-###### paginatePath
-
-(`string`) The path element used during pagination (`https://example.org/page/2`). Default is `page`.
+See [configure pagination](/templates/pagination/#configuration).
 
 ###### permalinks
 
@@ -962,4 +958,3 @@ Some use cases for this feature:
 [kind]: /getting-started/glossary/#page-kind
 [output format]: /getting-started/glossary/#output-format
 [type]: /getting-started/glossary/#content-type
-
diff --git a/content/en/getting-started/glossary.md b/content/en/getting-started/glossary.md
@@ -287,15 +287,19 @@ A file within a [page bundle](#page-bundle). Capture one or more page resources
 
 ###### pager
 
-Created during [pagination](#pagination), a pager contains a subset of a section list, and navigation links to other pagers.
+Created during [pagination](#pagination), a pager contains a subset of a list page and navigation links to other pagers.
 
 ###### paginate
 
-To split a [section](#section) list into two or more [pagers](#pager) See&nbsp;[details](/templates/pagination/).
+To split a list page into two or more subsets.
 
 ###### pagination
 
-The process of [paginating](#paginate) a [section](#section) list.
+The process of [paginating](#paginate) a list page. See&nbsp;[details](/templates/pagination/).
+
+###### paginator
+
+A collection of [pagers](#pager).
 
 ###### parameter
 

diff --git a/content/en/methods/page/Paginate.md b/content/en/methods/page/Paginate.md
@@ -12,15 +12,17 @@ action:
 
 [Pagination] is the process of splitting a list page into two or more pagers, where each pager contains a subset of the page collection and navigation links to other pagers.
 
-By default, the number of elements on each pager is determined by the value of the `paginate` setting in your site configuration. The default value is `10`. Override the value in your site configuration by providing a second argument, an integer, when calling the `Paginate` method.
+By default, the number of elements on each pager is determined by your [site configuration]. The default is `10`. Override that value by providing a second argument, an integer, when calling the `Paginate` method.
+
+[site configuration]: /getting-started/configuration/#pagination
 
 {{% note %}}
 There is also a `Paginator` method on `Page` objects, but it can neither filter nor sort the page collection.
 
 The `Paginate` method is more flexible.
 {{% /note %}}
 
-You can invoke pagination on the home page template, [`section`] templates, [`taxonomy`] templates, and [`term`] templates.
+You can invoke pagination on `home`, `section`, `taxonomy`, and `term` pages.
 
 {{< code file=layouts/_default/list.html >}}
 {{ $pages := where .Site.RegularPages "Section" "articles" }}
@@ -37,14 +39,11 @@ In the example above, we:
 2. Sort the collection by title
 3. Paginate the collection, with 7 elements per pager
 4. Range over the paginated page collection, rendering a link to each page
-5. Call the internal "pagination" template to create the navigation links between pagers.
+5. Call the embedded pagination template to create navigation links between pagers
 
 {{% note %}}
 Please note that the results of pagination are cached. Once you have invoked either the `Paginator` or `Paginate` method, the paginated collection is immutable. Additional invocations of these methods will have no effect.
 {{% /note %}}
 
 [context]: /getting-started/glossary/#context
 [pagination]: /templates/pagination/
-[`section`]: /getting-started/glossary/#section
-[`taxonomy`]: /getting-started/glossary/#taxonomy
-[`term`]: /getting-started/glossary/#term
diff --git a/content/en/methods/page/Paginator.md b/content/en/methods/page/Paginator.md
@@ -10,9 +10,13 @@ action:
   signatures: [PAGE.Paginator]
 ---
 
-[Pagination] is the process of splitting a list page into two or more pagers, where each pager contains a subset of the page collection and navigation links to other pagers. The number of elements on each pager is determined by the value of the `paginate` setting in your site configuration. The default value is `10`.
+[Pagination] is the process of splitting a list page into two or more pagers, where each pager contains a subset of the page collection and navigation links to other pagers.
 
-You can invoke pagination on the home page template, [`section`] templates, [`taxonomy`] templates, and [`term`] templates. Each of these receive a collection of regular pages in [context]. When you invoke the `Paginator` method, it paginates the page collection received in context.
+The number of elements on each pager is determined by your [site configuration]. The default is `10`.
+
+[site configuration]: /getting-started/configuration/#pagination
+
+You can invoke pagination on `home`, `section`, `taxonomy`, and `term` pages. Each of these receive a collection of regular pages in [context]. When you invoke the `Paginator` method, it paginates the page collection received in context.
 
 {{< code file=layouts/_default/list.html >}}
 {{ range .Paginator.Pages }}
@@ -21,7 +25,7 @@ You can invoke pagination on the home page template, [`section`] templates, [`ta
 {{ template "_internal/pagination.html" . }}
 {{< /code >}}
 
-In the example above, the internal "pagination" template creates the navigation links between pagers.
+In the example above, the embedded pagination template creates navigation links between pagers.
 
 {{% note %}}
 Although simple to invoke, with the `Paginator` method you can neither filter nor sort the page collection. It acts upon the page collection received in context.
@@ -37,6 +41,3 @@ Please note that the results of pagination are cached. Once you have invoked eit
 
 [context]: /getting-started/glossary/#context
 [pagination]: /templates/pagination/
-[`section`]: /getting-started/glossary/#section
-[`taxonomy`]: /getting-started/glossary/#taxonomy
-[`term`]: /getting-started/glossary/#term
diff --git a/content/en/methods/pager/PageSize.md b/content/en/methods/pager/PageSize.md
@@ -1,15 +1,27 @@
 ---
 title: PageSize
-description: Returns the maximum number of pages per pager.
+description: Returns the number of pages per pager.
 categories: []
 keywords: []
 action:
   related:
     - methods/page/Paginate
   returnType: int
   signatures: [PAGER.PageSize]
+expiryDate: 2025-06-09 # deprecated 2024-06-09
 ---
 
+{{% deprecated-in 0.128.0 %}}
+Use [`PAGER.PagerSize`] instead.
+
+[`PAGER.PagerSize`]: /methods/pager/pagersize/
+{{% /deprecated-in %}}
+
+The number of pages per pager is determined by the optional second argument passed to the [`Paginate`] method, falling back to the `pagerSize` as defined in your [site configuration].
+
+[`Paginate`]: /methods/page/paginate/
+[site configuration]: /templates/pagination/#configuration
+
 ```go-html-template
 {{ $pages := where site.RegularPages "Type" "posts" }}
 {{ $paginator := .Paginate $pages }}

diff --git a/content/en/methods/pager/PagerSize.md b/content/en/methods/pager/PagerSize.md
@@ -0,0 +1,31 @@
+---
+title: PagerSize
+description: Returns the number of pages per pager.
+categories: []
+keywords: []
+action:
+  related:
+    - methods/page/Paginate
+  returnType: int
+  signatures: [PAGER.PagerSize]
+---
+
+{{< new-in 0.128.0 >}}
+
+The number of pages per pager is determined by the optional second argument passed to the [`Paginate`] method, falling back to the `pagerSize` as defined in your [site configuration].
+
+[`Paginate`]: /methods/page/paginate/
+[site configuration]: /templates/pagination/#configuration
+
+```go-html-template
+{{ $pages := where site.RegularPages "Type" "posts" }}
+{{ $paginator := .Paginate $pages }}
+
+{{ range $paginator.Pages }}
+  <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+
+{{ with $paginator }}
+  {{ .PagerSize }}
+{{ end }}
+```
diff --git a/content/en/methods/site/IsMultiLingual.md b/content/en/methods/site/IsMultiLingual.md
@@ -7,6 +7,7 @@ action:
   related: []
   returnType: bool
   signatures: [SITE.IsMultiLingual]
+expiryDate: 2025-03-16 # deprecated 2024-03-16
 ---
 
 {{% deprecated-in 0.124.0 %}}

diff --git a/content/en/methods/site/LastChange.md b/content/en/methods/site/LastChange.md
@@ -7,6 +7,7 @@ action:
   related: []
   returnType: time.Time
   signatures: [SITE.LastChange]
+expiryDate: 2025-02-19 # deprecated 2024-02-19  
 ---
 
 {{% deprecated-in 0.123.0 %}}