Pagination

Blogs commonly list only the 20-30 most recent posts on the index page and then have a link to older posts.

We can paginate any collection or data structure by defining it in the front matter of the index page, here is an example (using the sigpipe collection):

---
title: SIGPIPE 13
permalink: /:path/
paginate:
  permalink: /:path/page/:num/
  collection: sigpipe
  per_page: 10
---
{%- for post in page.paginator.posts %}

  ...

{%- endfor %}

If the sigpipe collection has 35 posts then 4 instances of the page above will be created, the first instance will use page.permalink as permalink and the rest will use page.paginate.permalink resulting in these four pages being generated:

sigpipe
├── index.html
└── page
    ├── 2
    │   └── index.html
    ├── 3
    │   └── index.html
    └── 4
        └── index.html

Each instance have access to page.paginator which is an object with the following fields:

• posts: An array of posts for the current page, in our example that would be post 1-10, 11-20, 21-30, and 31-35 for the respective pages.
• index: The one-based index for the current page. This is used for :num in the permalink.
• pages: All generated pages, useful if you want to create numbered links for quickly jumping to a specific page.
• first: The first page, or nil if on the first page.
• last: The last page, or nil if on the last page.
• next: The next page, or nil if on the last page.
• previous: The previous page, or nil if on the first page.

When setting up pagination in a page’s front matter it is possible to set the following values:

• collection: Name of collection to paginate.
• data: Name of data to paginate, this corresponds to site.«data».
• sort: Set to true to sort the collection or data structure (array or hash) before pagination.
• sort_by: Sort by a specific field. If paginating a hash data structure it will read field from the value objects.
• per_page: Number of posts per page.