Document new pagination config

.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",

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
-

content/en/getting-started/glossary.md

@@ -287,15 +287,15 @@ 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 [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 [details](/templates/pagination/).
 
 ###### parameter
 

content/en/templates/pagination.md

@@ -1,6 +1,6 @@
 ---
 title: Pagination
-description: Hugo supports pagination for your homepage, section pages, and taxonomies.
+description: Split a list page into two or more subsets.
 categories: [templates]
 keywords: [lists,sections,pagination]
 menu:
@@ -12,21 +12,71 @@ toc: true
 aliases: [/extras/pagination,/doc/pagination/]
 ---
 
-The real power of Hugo pagination shines when combined with the [`where`] function and its SQL-like operators: [`first`], [`last`], and [`after`]. You can even [order the content][lists] the way you've become used to with Hugo.
+Displaying a large page collection on a single list page is not user-friendly:
 
-## Configure pagination
+- A massive list can be intimidating and difficult to navigate. Users may get lost in the sheer volume of information.
+- Large pages take longer to load, which can frustrate users and lead to them abandoning the site.
+- Without any filtering or organization, finding a specific item becomes a tedious scrolling exercise.
 
-Pagination can be configured in your [site configuration][configuration]:
+Improve usability by paginating `home`, `section`, `taxonomy`, and `term` pages.
 
-paginate
-: default = `10`. This setting can be overridden within the template.
+## Terminology
 
-paginatePath
-: default = `page`. Allows you to set a different path for your pagination pages.
+paginate
+: To split a list page into two or more subsets.
+
+pagination
+: The process of paginating a list page.
+
+pager
+: Created during pagination, a pager contains a subset of a list page and navigation links to other pagers.
+
+## Configuration
+
+Control pagination behavior in your site configuration:
+
+{{< code-toggle file=hugo config=pagination />}}
+
+disableAliases
+: (`bool`) Whether to disable alias generation for the first pager. Default is `false`.
+
+pagerSize
+: (`int`) The number of pages per pager. Default is `10`.
+
+path
+: (`string`) The segment of each pager URL indicating that the target page is a pager. Default is `page`.
+
+With multilingual sites you can define pagination behavior for each language:
+
+{{< code-toggle file=hugo >}}
+[languages.en]
+contentDir = 'content/en'
+languageCode = 'en-US'
+languageDirection = 'ltr'
+languageName = 'English'
+weight = 1
+[languages.en.pagination]
+disableAliases = true
+pagerSize = 10
+path = 'page'
+[languages.de]
+contentDir = 'content/de'
+languageCode = 'de-DE'
+languageDirection = 'ltr'
+languageName = 'Deutsch'
+weight = 2
+[languages.de.pagination]
+disableAliases = true
+pagerSize = 20
+path = 'blatt'
+{{< /code-toggle >}}
 
-Setting `paginate` to a positive value will split the list pages for the homepage, sections and taxonomies into chunks of that size. But note that the generation of the pagination pages for sections, taxonomies and homepage is *lazy* --- the pages will not be created if not referenced by a `.Paginator` (see below).
+{{% note %}}
+Hugo does not paginate a list page until you invoke the [`Paginate`] or [`Paginator`] method on a `Page` object. See details below.
 
-`paginatePath` is used to adapt the `URL` to the pages in the paginator (the default setting will produce URLs on the form `/page/1/`.
+[`Paginate`]: /methods/page/paginate/
+[`Paginator`]: /methods/page/paginator/
+{{% /note %}}
 
 ## List paginator pages
 
@@ -41,7 +91,7 @@ There are two ways to configure and use a `.Paginator`:
   * `{{ range (.Paginate ( first 50 .Pages.ByTitle )).Pages }}` or
   * `{{ range (.Paginate .RegularPagesRecursive).Pages }}`.
 
-For a given **Page**, it's one of the options above. The `.Paginator` is static and cannot change once created.
+For a given `Page`, it's one of the options above. The `.Paginator` is static and cannot change once created.
 
 If you call `.Paginator` or `.Paginate` multiple times on the same page, you should ensure all the calls are identical. Once *either* `.Paginator` or `.Paginate` is called while generating a page, its result is cached, and any subsequent similar call will reuse the cached result. This means that any such calls which do not match the first one will not behave as written.
 
@@ -156,6 +206,5 @@ The pages are built on the following form (`BLANK` means no value):
 [`first`]: /functions/collections/first/
 [`last`]: /functions/collections/last/
 [`after`]: /functions/collections/after/
-[configuration]: /getting-started/configuration/
 [lists]: /templates/lists/
 [`where`]: /functions/collections/where/

data/docs.yaml

@@ -307,6 +307,9 @@ chroma:
     - gherkin
     - Gherkin
     Name: Gherkin
+  - Aliases:
+    - gleam>
+    Name: Gleam
   - Aliases:
     - glsl
     Name: GLSL
@@ -1583,8 +1586,12 @@ config:
     term:
     - html
     - rss
-  paginate: 10
-  paginatePath: page
+  paginate: 0
+  paginatePath: ""
+  pagination:
+    disableAliases: false
+    pagerSize: 10
+    path: page
   panicOnWarning: false
   params: {}
   permalinks:
@@ -1761,6 +1768,8 @@ config_helpers:
       _merge: shallow
     outputs:
       _merge: none
+    pagination:
+      _merge: none
     params:
       _merge: deep
     permalinks: