ref: a6d22bcf7dd96a8dd30e7ce27cb88b45f85c2407
dir: /docs/content/extras/pagination.md/
---
aliases:
- /doc/pagination/
date: 2014-01-01
menu:
main:
parent: extras
next: /extras/highlighting
prev: /extras/shortcodes
title: Pagination
weight: 80
---
Hugo supports pagination for the home page, sections and taxonomies.
## Configuration
Pagination can be configured in the site configuration (e.g. `config.toml`):
* `Paginate` (default `0`)
* `PaginatePath` (default `page`)
Setting `Paginate` to a positive value will split the list pages for the home page, sections and taxonomies into chunks of that size.[^lazy] `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 the pages
**A `.Paginator` is provided to help building a pager menu. This is only relevant for the templates for the home page and the list pages (sections and taxonomies).**
There are two ways to configure and use a `.Paginator`:
1. The simplest way is just to call `.Paginator.Pages` from a template. It will contain the pages for *that page* .
2. Select a sub-set of the pages with the available template functions and pass the slice to `.Paginate`, i.e. `{{ range (.Paginate (where .Data.Pages "Type" "post")).Pages }}`
For a given **Node**, it's one of the options above. The `.Paginator` is static and cannot change once created.
## Build the navigation
The `.Paginator` contains enough information to build a paginator interface.
The easiest way to add this to your pages is to include the built-in template (with `Bootstrap`-compatible styles):
```
{{ template "_internal/pagination.html" . }}
```
**Note:** If you use any filters or sorting 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:
```
{{ $paginator := .Paginate (where .Data.Pages "Type" "post") }}
{{ template "_internal/pagination.html" . }}
{{ range $paginator.Pages }}
{{ .Title }}
{{ end }}
```
Without the where-filter, the above is simpler:
```
{{ template "_internal/pagination.html" . }}
{{ range .Paginator.Pages }}
{{ .Title }}
{{ end }}
```
If you want to build custom navigation, you can do so using the `.Paginator` object:
* `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):
```
[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
....
```
[^lazy]: The generation of the pagination pages for sections, taxonomies and home page is *lazy* -- they will not be created if not referenced by a `.Paginator`.