GuideAdd content to your site
Pagination
Split a list or a collection over several pages, generate a page per item, and link the pages together.
Pagination turns one template into several pages: a blog index of ten posts per page, or one page per product of a
data file. A page declares what it paginates in its pagination front matter, and the paginate step writes one
page per slice. This page covers the options, the variables each page gets, permalinks, navigation, and the limits.
Paginate a listLink to this heading
---
pagination:
data: products # a name, or a dotted path such as collections.post or site.products
size: 2 # items per page
alias: items # optional: a name for the items of the page
resolve: values # optional, for an object: paginate its values instead of its keys
---
data names any value the page can resolve: its own front matter, folder data, site data or collections. A list is
paginated item by item. An object is paginated by key, or by value with resolve: values.
Paginate a collectionLink to this heading
The default workflow builds collections before pagination, so a page can paginate collections.<tag>:
---
pagination:
data: collections.post
size: 2
alias: posts
---
<h1>Page {{ pagination.pageNumber | plus: 1 }} of {{ pagination.pages.size }}</h1>
{%- for post in posts %}
<a href="{{ post.data.url | replace: 'index.html', '' }}">{{ post.data.title }}</a>
{%- endfor %}
With five posts, this writes blog/index.html, blog/1/index.html and blog/2/index.html. The posts come in the
order of the collection: oldest first (see Collections). pagination.data takes a name, not
a filter chain, so a page cannot sort or filter what it paginates.
What each page getsLink to this heading
| Variable | Value |
|---|---|
pagination.items |
the items of this page |
pagination.pageNumber |
the index of this page, from 0 |
pagination.pages |
every page, each { items, pageNumber, href } |
pagination.hrefs |
the path of every page |
pagination.page.next, previous, first, last |
those pages, { items, pageNumber, href }; next and previous are nil at the ends |
| the alias | the items of this page; with size: 1, the item itself |
url |
this page's url |
An href is the path of the page's file, such as /blog/1/index.html. Remove index.html for clean links.
NavigationLink to this heading
<nav>
{%- if pagination.page.previous %}<a href="{{ pagination.page.previous.href | replace: 'index.html', '' }}">Previous</a>{% endif %}
{%- for p in pagination.pages %}
<a href="{{ p.href | replace: 'index.html', '' }}"{% if p.pageNumber == pagination.pageNumber %} aria-current="page"{% endif %}>{{ p.pageNumber | plus: 1 }}</a>
{%- endfor %}
{%- if pagination.page.next %}<a href="{{ pagination.page.next.href | replace: 'index.html', '' }}">Next</a>{% endif %}
</nav>
Pagination variables only link the pages generated from the same template.
PermalinksLink to this heading
Without a permalink, the first page keeps the template's path and the others get a numbered folder:
products/index.html, products/1/index.html, products/2/index.html. A permalink is rendered for each page,
with its pagination and its alias, so it can name pages after their content:
- name: Widget
slug: widget
- name: Gadget
slug: gadget
---
pagination:
data: products
size: 1
alias: product
permalink: "products/{{ product.slug }}/"
---
<h1>{{ product.name }}</h1>
This writes products/widget/index.html and products/gadget/index.html. A permalink can use
pagination.pageNumber ("blog/page-{{ pagination.pageNumber | plus: 1 }}/") but not the href values, which come
from the permalinks. A permalink that renders the same path for every page is ignored, and the pages get numbered
folders.
Paginate an objectLink to this heading
---
pagination:
data: colors
size: 1
alias: color
resolve: values
permalink: "colors/{{ pagination.pageNumber }}.html"
colors:
red: "#f00"
green: "#0f0"
---
{{ color }}
Without resolve: values, the items are the keys (red, green).
LimitsLink to this heading
- A list with no items gives no page at all: the template is not written.
- The paginated page is in
collections.allonce, with the url of its first page. paginationhas noreverse,filterorbeforeoption. Sort or filter the data where it is made, or keep a data file in the order you want.