Pagination

Edit this page on Github

Items can be organized in pages thanks to pagination generator and will be accessible with URLs like /blog/page2/.

The following examples assume that you are using a site with Spresso theme. If not, you can create one with new:site command:

$ spress new:site example spresso

The simple way of add pagination to posts collection items is creating a index.html file at ./src/content/blog with the following content:

---
layout: "page"
title: "Blog posts"

generator: "pagination"
provider: "site.posts"
max_page: 1
sort_by: "date"
---
<h1>Posts</h1>
<ul>
    {% for post in page.pagination.items %}
        <li><a href="{{ post.url }}">{{ post.title }}</a></li>
    {% endfor %}
</ul>

{% include "paginator.html" %}

Attributes:

• generator: contains the name of the generator, in this case pagination.
• provider: The descriptor for the provider of the items (collection) to be paginated. site.posts is the default value. If you have a custom collection, for example events, this value would besite.events.
• max_page: The maximum number of item per page. Default value is 5.

Recompile your site and your page will be accesible at http://localhost:4000/blog/.

Files generated:

Sorting items

With sort_by and sort_type attributes you will be able to control how items are sorted at pagination generator. sort_type only supports ascending and descending values. descending is the default behavior. sort_by attribute contains the name of the attribute used as criteria to sort.

Open the ./src/content/blog/index.html file and add sort_type: "ascending" attribute at Front matter block. Then, recompile your site. Posts at http://localhost:4000/blog/ should be in reverse order.

Page permalink

The default permalink for each generated page is /page:num. The :num placeholder will be replaced with the number of page starting with 2. This permalink is relative to the folter in where generator was defined, in the case of prior example, /blog folder and that means URLs generated starting by /blog.