mirror of
https://github.com/gohugoio/hugo.git
synced 2026-08-25 07:48:52 +00:00
Document new pagination config
This commit is contained in:
Joe Mooring
committed by
Bjørn Erik Pedersen
Bjørn Erik Pedersen
parent
0af8be439f
commit
4449d530d4
@@ -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",
|
||||
|
||||
@@ -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/).
|
||||
|
||||
@@ -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 %}}
|
||||
|
||||
@@ -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 %}}
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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 [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/).
|
||||
|
||||
###### paginator
|
||||
|
||||
A collection of [pagers](#pager).
|
||||
|
||||
###### parameter
|
||||
|
||||
|
||||
@@ -12,7 +12,9 @@ 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.
|
||||
@@ -20,7 +22,7 @@ There is also a `Paginator` method on `Page` objects, but it can neither filter
|
||||
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,7 +39,7 @@ 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.
|
||||
@@ -45,6 +47,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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: PageSize
|
||||
description: Returns the maximum number of pages per pager.
|
||||
description: Returns the number of pages per pager.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
@@ -8,8 +8,20 @@ action:
|
||||
- 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 }}
|
||||
|
||||
@@ -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 }}
|
||||
```
|
||||
@@ -7,6 +7,7 @@ action:
|
||||
related: []
|
||||
returnType: bool
|
||||
signatures: [SITE.IsMultiLingual]
|
||||
expiryDate: 2025-03-16 # deprecated 2024-03-16
|
||||
---
|
||||
|
||||
{{% deprecated-in 0.124.0 %}}
|
||||
|
||||
@@ -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 %}}
|
||||
|
||||
+239
-111
@@ -1,161 +1,289 @@
|
||||
---
|
||||
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]
|
||||
keywords: []
|
||||
menu:
|
||||
docs:
|
||||
parent: templates
|
||||
weight: 100
|
||||
weight: 100
|
||||
weight: 180
|
||||
weight: 180
|
||||
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 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]:
|
||||
|
||||
paginate
|
||||
: default = `10`. This setting can be overridden within the template.
|
||||
|
||||
paginatePath
|
||||
: default = `page`. Allows you to set a different path for your pagination pages.
|
||||
|
||||
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).
|
||||
|
||||
`paginatePath` is used to adapt the `URL` to the pages in the paginator (the default setting will produce URLs on the form `/page/1/`.
|
||||
|
||||
## List paginator pages
|
||||
Improve usability by paginating `home`, `section`, `taxonomy`, and `term` pages.
|
||||
|
||||
{{% note %}}
|
||||
Paginate a page collection in list templates for these page kinds: `home`, `section`, `taxonomy`, or `term`. You cannot paginate a page collection in a template for the `page` page kind.
|
||||
The most common templating mistake related to pagination is invoking pagination more than once for a given list page. See the [caching](#caching) section below.
|
||||
{{% /note %}}
|
||||
|
||||
There are two ways to configure and use a `.Paginator`:
|
||||
## Terminology
|
||||
|
||||
1. The simplest way is just to call `.Paginator.Pages` from a template. It will contain the pages for *that page*.
|
||||
2. Select another set of pages with the available template functions and ordering options, and pass the slice to `.Paginate`, e.g.
|
||||
* `{{ range (.Paginate ( first 50 .Pages.ByTitle )).Pages }}` or
|
||||
* `{{ range (.Paginate .RegularPagesRecursive).Pages }}`.
|
||||
paginate
|
||||
: To split a list page into two or more subsets.
|
||||
|
||||
For a given **Page**, it's one of the options above. The `.Paginator` is static and cannot change once created.
|
||||
pagination
|
||||
: The process of paginating a list page.
|
||||
|
||||
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.
|
||||
pager
|
||||
: Created during pagination, a pager contains a subset of a list page and navigation links to other pagers.
|
||||
|
||||
(Remember that function arguments are eagerly evaluated, so a call like `$paginator := cond x .Paginator (.Paginate .RegularPagesRecursive)` is an example of what you should *not* do. Use `if`/`else` instead to ensure exactly one evaluation.)
|
||||
paginator
|
||||
: A collection of pagers.
|
||||
|
||||
The global page size setting (`Paginate`) can be overridden by providing a positive integer as the last argument. The examples below will give five items per page:
|
||||
## Configuration
|
||||
|
||||
* `{{ range (.Paginator 5).Pages }}`
|
||||
* `{{ $paginator := .Paginate (where .Pages "Type" "posts") 5 }}`
|
||||
Control pagination behavior in your site configuration. These are the default settings:
|
||||
|
||||
It is also possible to use the `GroupBy` functions in combination with pagination:
|
||||
{{< 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 the 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 >}}
|
||||
|
||||
## Methods
|
||||
|
||||
To paginate a `home`, `section`, `taxonomy`, or `term` page, invoke either of these methods on the `Page` object in the corresponding template:
|
||||
|
||||
- [`Paginate`]
|
||||
- [`Paginator`]
|
||||
|
||||
The `Paginate` method is more flexible, allowing you to:
|
||||
|
||||
- Paginate any page collection
|
||||
- Filter, sort, and group the page collection
|
||||
- Override the number of pages per pager as defined in your site configuration
|
||||
|
||||
By comparison, the `Paginator` method paginates the page collection passed into the template, and you cannot override the number of pages per pager.
|
||||
|
||||
[`Paginate`]: /methods/page/paginate/
|
||||
[`Paginator`]: /methods/page/paginator/
|
||||
|
||||
## Examples
|
||||
|
||||
To paginate a list page using the `Paginate` method:
|
||||
|
||||
```go-html-template
|
||||
{{ range (.Paginate (.Pages.GroupByDate "2006")).PageGroups }}
|
||||
{{ $pages := where site.RegularPages "Type" "posts" }}
|
||||
{{ $paginator := .Paginate $pages.ByTitle 7 }}
|
||||
|
||||
{{ range $paginator.Pages }}
|
||||
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
|
||||
{{ end }}
|
||||
|
||||
{{ template "_internal/pagination.html" . }}
|
||||
```
|
||||
|
||||
## Build the navigation
|
||||
In the example above, we:
|
||||
|
||||
1. Build a page collection
|
||||
2. Sort the page collection by title
|
||||
3. Paginate the page collection, with 7 pages per pager
|
||||
4. Range over the paginated page collection, rendering a link to each page
|
||||
5. Call the embedded pagination template to create navigation links between pagers
|
||||
|
||||
|
||||
To paginate a list page using the `Paginator` method:
|
||||
|
||||
```go-html-template
|
||||
{{ range .Paginator.Pages }}
|
||||
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
|
||||
{{ end }}
|
||||
|
||||
{{ template "_internal/pagination.html" . }}
|
||||
```
|
||||
|
||||
In the example above, we:
|
||||
|
||||
1. Paginate the page collection passed into the template, with the default number of pages per pager
|
||||
2. Range over the paginated page collection, rendering a link to each page
|
||||
3. Call the embedded pagination template to create navigation links between pagers
|
||||
|
||||
## Caching
|
||||
|
||||
{{% note %}}
|
||||
The most common templating mistake related to pagination is invoking pagination more than once for a given list page.
|
||||
{{% /note %}}
|
||||
|
||||
Regardless of pagination method, the initial invocation is cached and cannot be changed. If you invoke pagination more than once for a given list page, subsequent invocations use the cached result. This means that subsequent invocations will not behave as written.
|
||||
|
||||
When paginating conditionally, do not use the `compare.Conditional` function due to its eager evaluation of arguments. Use an `if-else` construct instead.
|
||||
|
||||
[`compare.Conditional`]: /functions/compare/conditional/
|
||||
|
||||
## Grouping
|
||||
|
||||
Use pagination with any of the grouping methods. For example:
|
||||
|
||||
```go-html-template
|
||||
{{ $pages := where site.RegularPages "Type" "posts" }}
|
||||
{{ $paginator := .Paginate ($pages.GroupByDate "Jan 2006") }}
|
||||
|
||||
{{ range $paginator.PageGroups }}
|
||||
<h2>{{ .Key }}</h2>
|
||||
{{ range .Pages }}
|
||||
<h3><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h3>
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
|
||||
{{ template "_internal/pagination.html" . }}
|
||||
```
|
||||
|
||||
[grouping methods]: /quick-reference/page-collections/#group
|
||||
|
||||
## Navigation
|
||||
|
||||
As shown in the examples above, the easiest way to add navigation between pagers is with Hugo's embedded pagination template:
|
||||
|
||||
```go-html-template
|
||||
{{ template "_internal/pagination.html" . }}
|
||||
```
|
||||
|
||||
The embedded pagination template has two formats: `default` and `terse`. The above is equivalent to:
|
||||
|
||||
```go-html-template
|
||||
{{ template "_internal/pagination.html" (dict "page" . "format" "default") }}
|
||||
```
|
||||
|
||||
The `terse` format has fewer controls and page slots, consuming less space when styled as a horizontal list. To use the `terse` format:
|
||||
|
||||
```go-html-template
|
||||
{{ template "_internal/pagination.html" (dict "page" . "format" "terse") }}
|
||||
```
|
||||
|
||||
{{% note %}}
|
||||
To override Hugo's embedded pagination template, copy the [source code] to a file with the same name in the layouts/partials directory, then call it from your templates using the [`partial`] function:
|
||||
|
||||
`{{ partial "pagination" . }}`
|
||||
`{{ partial "pagination.html" . }}`
|
||||
|
||||
[`partial`]: /functions/partials/include/
|
||||
[source code]: {{% eturl pagination %}}
|
||||
{{% /note %}}
|
||||
|
||||
The easiest way to add this to your pages is to include the embedded template:
|
||||
Create custom navigation components using any of the `Pager` methods:
|
||||
|
||||
```go-html-template
|
||||
{{ template "_internal/pagination.html" . }}
|
||||
{{< list-pages-in-section path=/methods/pager >}}
|
||||
|
||||
## Structure
|
||||
|
||||
The example below depicts the published site structure when paginating a list page.
|
||||
|
||||
With this content:
|
||||
|
||||
```text
|
||||
content/
|
||||
├── posts/
|
||||
│ ├── _index.md
|
||||
│ ├── post-1.md
|
||||
│ ├── post-2.md
|
||||
│ ├── post-3.md
|
||||
│ └── post-4.md
|
||||
└── _index.md
|
||||
```
|
||||
|
||||
{{% note %}}
|
||||
If you use any filters or ordering functions to create your `.Paginator` *and* you want the navigation buttons to be shown before the page listing, you must create the `.Paginator` before it's used.
|
||||
{{% /note %}}
|
||||
And this site configuration:
|
||||
|
||||
The following example shows how to create `.Paginator` before its used:
|
||||
{{< code-toggle file=hugo >}}
|
||||
[pagination]
|
||||
disableAliases = false
|
||||
pagerSize = 2
|
||||
path = 'page'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
And this section template:
|
||||
|
||||
```go-html-template
|
||||
{{ $paginator := .Paginate (where .Pages "Type" "posts") }}
|
||||
{{ template "_internal/pagination.html" . }}
|
||||
{{ range $paginator.Pages }}
|
||||
{{ .Title }}
|
||||
{{ range (.Paginate .Pages).Pages }}
|
||||
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Without the `where` filter, the above example is even simpler:
|
||||
|
||||
```go-html-template
|
||||
{{ template "_internal/pagination.html" . }}
|
||||
{{ range .Paginator.Pages }}
|
||||
{{ .Title }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
If you want to build custom navigation, you can do so using the `.Paginator` object, which includes the following properties:
|
||||
The published site has this structure:
|
||||
|
||||
PageNumber
|
||||
: The current page's number in the pager sequence
|
||||
|
||||
URL
|
||||
: The relative URL to the current pager
|
||||
|
||||
Pages
|
||||
: The pages in the current pager
|
||||
|
||||
NumberOfElements
|
||||
: The number of elements on this page
|
||||
|
||||
HasPrev
|
||||
: Whether there are page(s) before the current
|
||||
|
||||
Prev
|
||||
: The pager for the previous page
|
||||
|
||||
HasNext
|
||||
: Whether there are page(s) after the current
|
||||
|
||||
Next
|
||||
: The pager for the next page
|
||||
|
||||
First
|
||||
: The pager for the first page
|
||||
|
||||
Last
|
||||
: The pager for the last page
|
||||
|
||||
Pagers
|
||||
: A list of pagers that can be used to build a pagination menu
|
||||
|
||||
PageSize
|
||||
: Size of each pager
|
||||
|
||||
TotalPages
|
||||
: The number of pages in the paginator
|
||||
|
||||
TotalNumberOfElements
|
||||
: The number of elements on all pages in this paginator
|
||||
|
||||
## Additional information
|
||||
|
||||
The pages are built on the following form (`BLANK` means no value):
|
||||
|
||||
```txt
|
||||
[SECTION/TAXONOMY/BLANK]/index.html
|
||||
[SECTION/TAXONOMY/BLANK]/page/1/index.html => redirect to [SECTION/TAXONOMY/BLANK]/index.html
|
||||
[SECTION/TAXONOMY/BLANK]/page/2/index.html
|
||||
....
|
||||
```text
|
||||
public/
|
||||
├── posts/
|
||||
│ ├── page/
|
||||
│ │ ├── 1/
|
||||
│ │ │ └── index.html <-- alias to public/posts/index.html
|
||||
│ │ └── 2/
|
||||
│ │ └── index.html
|
||||
│ ├── post-1/
|
||||
│ │ └── index.html
|
||||
│ ├── post-2/
|
||||
│ │ └── index.html
|
||||
│ ├── post-3/
|
||||
│ │ └── index.html
|
||||
│ ├── post-4/
|
||||
│ │ └── index.html
|
||||
│ └── index.html
|
||||
└── index.html
|
||||
```
|
||||
|
||||
[`first`]: /functions/collections/first/
|
||||
[`last`]: /functions/collections/last/
|
||||
[`after`]: /functions/collections/after/
|
||||
[configuration]: /getting-started/configuration/
|
||||
[lists]: /templates/lists/
|
||||
[`where`]: /functions/collections/where/
|
||||
To disable alias generation for the first pager, change your site configuration:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[pagination]
|
||||
disableAliases = true
|
||||
pagerSize = 2
|
||||
path = 'page'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
Now the published site will have this structure:
|
||||
|
||||
```text
|
||||
public/
|
||||
├── posts/
|
||||
│ ├── page/
|
||||
│ │ └── 2/
|
||||
│ │ └── index.html
|
||||
│ ├── post-1/
|
||||
│ │ └── index.html
|
||||
│ ├── post-2/
|
||||
│ │ └── index.html
|
||||
│ ├── post-3/
|
||||
│ │ └── index.html
|
||||
│ ├── post-4/
|
||||
│ │ └── index.html
|
||||
│ └── index.html
|
||||
└── index.html
|
||||
```
|
||||
|
||||
@@ -27,16 +27,15 @@ See [Template Lookup](/templates/lookup-order/).
|
||||
{{ define "main" }}
|
||||
<main>
|
||||
{{ .Content }}
|
||||
<ul class="contents">
|
||||
{{ range .Paginator.Pages }}
|
||||
<li>{{ .Title }}
|
||||
<div>
|
||||
{{ partial "summary.html" . }}
|
||||
</div>
|
||||
</li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
{{ partial "pagination.html" . }}
|
||||
|
||||
{{ $pages := where site.RegularPages "Type" "posts" }}
|
||||
{{ $paginator := .Paginate $pages }}
|
||||
|
||||
{{ range $paginator.Pages }}
|
||||
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
|
||||
{{ end }}
|
||||
|
||||
{{ template "_internal/pagination.html" . }}
|
||||
</main>
|
||||
{{ end }}
|
||||
{{< /code >}}
|
||||
|
||||
@@ -79,7 +79,7 @@ Use `:=` to initialize a variable, and use `=` to assign a value to a variable t
|
||||
|
||||
###### When I paginate a list page, why is the page collection not filtered as specified?
|
||||
|
||||
You are probably invoking the [`Paginate`] or [`Paginator`] method more than once on the same page. See [details](/templates/pagination/#list-paginator-pages).
|
||||
You are probably invoking the [`Paginate`] or [`Paginator`] method more than once on the same page. See [details](/templates/pagination/).
|
||||
|
||||
###### Why are there two ways to call a shortcode?
|
||||
|
||||
|
||||
+11
-2
@@ -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:
|
||||
|
||||
Reference in New Issue
Block a user