diff --git a/.cspell.json b/.cspell.json index 95e3ed5cee..01d248e253 100644 --- 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/getting-started/configuration.md b/content/en/getting-started/configuration.md index 35c7d780ea..ed5fdf032c 100644 --- 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 index c86c3fc970..59a2b68e59 100644 --- a/content/en/getting-started/glossary.md +++ b/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 diff --git a/content/en/templates/pagination.md b/content/en/templates/pagination.md index 36dea0c8e5..5e5e67da74 100644 --- a/content/en/templates/pagination.md +++ b/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/ diff --git a/data/docs.yaml b/data/docs.yaml index 603519d764..3c7ec3cf2a 100644 --- a/data/docs.yaml +++ b/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: