Pagination #
To iterate over a data set and create pages for individual chunks of data, use pagination. Enable in your template’s front matter by adding the pagination
key. Consider the following template:
---
pagination:
data: testdata
size: 2
testdata:
- item1
- item2
- item3
- item4
---
<ol>
{%- for item in pagination.items %}
<li>{{ item }}</li>
{% endfor -%}
</ol>
We enable pagination and then give it a dataset with the data
key. We control the number of items in each chunk with size
. The pagination data variable will be populated with what you need to create each template. Here’s what’s in pagination
:
{
items: [], // Array of current page’s chunk of data
pageNumber: 0, // current page number, 0 indexed
// Cool URLs, added in v0.6.0
nextPageHref: "…", // put inside <a href="">Next Page</a>
previousPageHref: "…", // put inside <a href="">Previous Page</a>
firstPageHref: "…",
lastPageHref: "…",
hrefs: [], // Array of all page hrefs (in order)
// Uncool URLs (these include index.html file names)
nextPageLink: "…", // put inside <a href="">Next Page</a>
previousPageLink: "…", // put inside <a href="">Previous Page</a>
firstPageLink: "…", // added in v0.6.0
lastPageLink: "…", // added in v0.6.0
links: [], // Array of all page links (in order)
pageLinks: [], // Array of deprecated alias to `links`
data: …, // pointer to dataset
size: 1, // chunk sizes
}
If the above file were named paged.njk
, it would create two pages: _site/paged/0/index.html
and _site/paged/1/index.html
. These output paths are configurable with permalink
(see below).
Paging an Object New in v0.4.0 #
All of the examples thus far have paged Array data. Eleventy does allow paging objects too. Objects are resolved to pagination arrays using either the Object.keys
or Object.values
JavaScript functions. Consider the following Nunjucks template:
---
pagination:
data: testdata
size: 1
testdata:
itemkey1: itemvalue1
itemkey2: itemvalue2
itemkey3: itemvalue3
---
<ol>
{%- for item in pagination.items %}
<li>{{ item }}</li>
{% endfor -%}
</ol>
In this example, we would get 3 pages, with the paged items holding the object keys:
[
[ "itemkey1" ], // pagination.items[0] holds the object key
[ "itemkey2" ],
[ "itemkey3" ]
]
You can use these keys to get access to the original value: testdata[ pagination.items[0] ]
.
If you’d like the pagination to iterate over the values instead of the keys (using Object.values
instead of Object.keys
), add resolve: values
to your pagination
front matter:
---
pagination:
data: testdata
size: 1
resolve: values
testdata:
itemkey1: itemvalue1
itemkey2: itemvalue2
itemkey3: itemvalue3
---
This resolves to:
[
[ "itemvalue1" ], // pagination.items[0] holds the object value
[ "itemvalue2" ],
[ "itemvalue3" ]
]
Paginate a global or local data file #
Read more about Template Data Files. The only change here is that you point your data
pagination key to the global or local data instead of data in the front matter. For example, consider the following globalDataSet.json
file in your global data directory.
{
myData: [
"item1",
"item2",
"item3",
"item4"
]
}
Your front matter would look like this:
---
pagination:
data: globalDataSet.myData
size: 1
---
<ol>
{%- for item in pagination.items %}
<li>{{ item }}</li>
{% endfor -%}
</ol>
Remapping with permalinks #
Normally, front matter does not support template syntax, but permalink
does, enabling parametric URLs via pagination variables. Here’s an example of a permalink using the pagination page number:
---
permalink: different/page-{{ pagination.pageNumber }}/index.html
---
Writes to _site/different/page-0/index.html
, _site/different/page-1/index.html
, et cetera.
That means Nunjucks will also let you start your page numbers with 1 instead of 0, by just adding 1 here:
---
permalink: different/page-{{ pagination.pageNumber + 1 }}/index.html
---
Writes to _site/different/page-1/index.html
, _site/different/page-2/index.html
, et cetera.
Use page item data in the permalink #
You can do more advanced things like this:
---
pagination:
data: testdata
size: 1
testdata:
- My Item
permalink: different/{{ pagination.items[0] | slug }}/index.html
---
Using a universal slug
filter (transforms My Item
to my-item
), this outputs: _site/different/my-item/index.html
.
Aliasing to a different variable #
Ok, so pagination.items[0]
is ugly. We provide an option to alias this to something different.
---
pagination:
data: testdata
size: 1
alias: wonder
testdata:
- Item1
- Item2
permalink: different/{{ wonder | slug }}/index.html
---
You can use the alias in your content too {{ wonder }}.
This writes to _site/different/item1/index.html
and _site/different/item2/index.html
.
If your chunk size
is greater than 1, the alias will be an array instead of a single value.
---
pagination:
data: testdata
size: 2
alias: wonder
testdata:
- Item1
- Item2
- Item3
- Item4
permalink: different/{{ wonder[0] | slug }}/index.html
---
You can use the alias in your content too {{ wonder[0] }}.
This writes to _site/different/item1/index.html
and _site/different/item3/index.html
.
Blacklisting or Filtering Values New in v0.4.0 #
Use the filter
pagination property to remove values from paginated data.
---
pagination:
data: testdata
size: 1
filter:
- item3
testdata:
item1: itemvalue1
item2: itemvalue2
item3: itemvalue3
---
Paginates to:
[
[ "item1" ],
[ "item2" ],
]
This will work the same with paginated arrays or with resolve: values
for paginated objects.
---
pagination:
data: testdata
size: 1
resolve: values
filter:
- itemvalue3
testdata:
item1: itemvalue1
item2: itemvalue2
item3: itemvalue3
---
Paginates to:
[
[ "itemvalue1" ],
[ "itemvalue2" ],
]
Paging a Collection #
If you’d like to make a paginated list of all of your blog posts (any content with the tag post
on it), use something like the following template to iterate over a specific collection:
---
title: My Posts
pagination:
data: collections.post
size: 6
alias: posts
---
<ol>
{% for post in posts %}
<li><a href="{{ post.url | url }}">{{ post.data.title }}</a></li>
{% endfor %}
</ol>
The above generates a list of links but you could do a lot more. See what’s available in the Collection documentation (specifically templateContent
). If you’d like to use this to automatically generate Tag pages for your content, please read Quick Tip #004—Create Tag Pages for your Blog.
How to Reverse a Data Set prior to Pagination New in v0.7.0 #
Use reverse: true
.
As an aside, this could also be achieved in a more verbose way using the Collection API.
---
pagination:
data: testdata
size: 2
reverse: true
testdata:
- item1
- item2
- item3
- item4
---
Paginates to:
[
["item4", "item3"],
["item2", "item1"],
]
(More discussion at Issue #194)
Add All Pagination Pages to Collections New in v0.8.0 #
By default, any tags listed in a paginated template will only add the very first page to the appropriate collection.
Consider the following pagination template:
tags:
- myCollection
pagination:
data: testdata
size: 2
testdata:
- item1
- item2
- item3
- item4
This means that collections.myCollection
will have only the first page added to the collection array (_site/my-page/index.html
). However, if you’d like all the pagination pages to the collections, use addAllPagesToCollections: true
to the pagination front matter options like so:
tags:
- myCollection
pagination:
data: testdata
size: 2
addAllPagesToCollections: true
testdata:
- item1
- item2
- item3
- item4
Now collections.myCollection
will have both output pages in the collection array (_site/my-page/index.html
and _site/-my-page/1/index.html
).
Full Pagination Option List #
data
(String) Lodash.get path to point to the target data set.size
(Number, required)alias
(String) Lodash.set path to point to the property to set.resolve: values
New in v0.4.0filter
(Array) New in v0.4.0reverse: true
(Boolean) New in v0.7.0addAllPagesToCollections: true
(Boolean) New in v0.8.0