J1 Paginator · Page Paginator of Posts for J1 Template

The Generator forms the core of the pagination logic. It is responsible for reading the posts and collections in your site and split them correctly across multiple pages according to the supplied configuration. It also performs the necessary functions to link to the previous and next pages in the page-sets that it generates.

The code was based on the original design of Jekyll Paginate and features were sourced from discussions such as #27 (thanks Günter Kits).

Site configuration

The pagination gem is configured in the site configuration file _config.yml by including the pagination configuration element

#---------------------------------------------------------------------
# Site configuration for the Jekyll 3 Pagination Gem
# The values here represent the defaults if nothing is set
#
pagination:
  # Site-wide kill switch, disabled here it doesn't run at all
  #
  enabled:        true
  # Set to 'true' to enable pagination debugging. This can be enabled in the
  #site config or only for individual pagination pages
  #
  debug:          false
  # The default document collection to paginate if nothing is specified
  # ('posts' is default)
  #
  collection:     posts
  # How many objects per paginated page, used to be `paginate`
  # (default: 0, means all)
  #
  per_page: 10
  # The permalink structure for the paginated pages (this can be any level deep)
  # Examples:
  #
  #   # Pages are simple html files
  #   permalink: '/page/:num.html
  #   # Pages are html files, linked jekyll extensionless permalink style.
  #   permalink: '/page/:num'
  #   # Pages are index.html inside this folder (default)
  #   permalink: '/page/:num/'
  #
  permalink:      '/page/:num/'
  # Optional the title format for the paginated pages (supports :title for
  # original page title, :num for pagination page number, :max for total number
  # of pages)
  #
  title:          ':title - page :num'
  # Limit how many pagenated pages to create (default: 0, means all)
  #
  limit:          0
  # Optional, defines the field that the posts should be sorted on (omit to
  # default to 'date')
  #
  sort_field:     date
  # Optional, sorts the posts in reverse order (omit to default decending or
  # sort_reverse: true)
  #
  sort_reverse:   true
  # Optional, the default category to use, omit or just leave this as 'posts'
  # to get a backwards-compatible behavior (all posts)
  #
  category:       posts
  # Optional, the default tag to use, omit to disable
  #
  tag:            ''
  # Optional, the default locale to use, omit to disable (depends on a field
  # 'locale' to be specified in the posts, in reality this can be any value,
  # suggested are the Microsoft locale-codes (e.g. en_US, en_GB) or simply the
  # ISO-639 language code)
  #
  locale:         ''
  # Optional,omit or set both before and after to zero to disable.
  # Controls how the pagination trail for the paginated pages look like.
  #
  trail:
    before:       2
    after:        2

Also ensure that you remove the old jekyll-paginate gem from your plugins list and add the new one jekyll-paginate-v2 instead.

# ---------------------------------------------------------------
# Plugin settings (gem)
#
plugins:
  - jekyll-paginate-v2

Page configuration

To enable pagination on a page then simply include the minimal pagination configuration in the page front-matter:

---
layout:           page
pagination:
  enabled:        true
---

Then you can use the normal paginator.posts logic to iterate through the posts.

{% for post in paginator.posts %}
  <h1>{{ post.title }}</h1>
{% endfor %}

And to display pagination links, simply

{% if paginator.total_pages > 1 %}
<ul>
  {% if paginator.previous_page %}
  <li>
    <a href="{{ paginator.previous_page_path | prepend: site.baseurl }}">Newer</a>
  </li>
  {% endif %}
  {% if paginator.next_page %}
  <li>
    <a href="{{ paginator.next_page_path | prepend: site.baseurl }}">Older</a>
  </li>
  {% endif %}
</ul>
{% endif %}

All posts that have the hidden: true flag set in their front matter gets ignored by the pagination logic of J1 Paginator. Following fields are available on the paginator object.

Table 1. Paginator object fields
Field	Description
`per_page`	Maximum number of posts or documents on each pagination page.
`posts`	The list of post objects that belong to this pagination page.
`total_posts`	Total number of posts included in pagination.
`total_pages`	Total number of pagination pages created.
`page`	Number of the current pagination page.
`page_path`	The relative Url path of the current pagination page.
`previous_page`	Number of the previous page in the pagination. Value `nil` returned if no previous page is available.
`previous_page_path`	The relative Url of the previous page. Value `nil` returned if no previous page is available.
`next_page`	Number of the next page in the pagination. Value `nil` returned if there is no next page available.
`next_page_path`	The relative Url of the next page in the pagination. Value `nil` returned if there is no next page available.
`first_page`	Number of the first page in the pagination. Usually this is: 1.
`first_page_path`	The relative Url of the first page in the pagination.
`last_page`	Number of the last page in the pagination (this is equal to `total_pages`).
`last_page_path`	The relative Url of the last page in the pagination.
`page_trail`	Find more on the pagination trail structure at Creating Pagination Trails.

The code is fully backwards compatible and you will have access to all the paginator variables of Paginator V1 defined in the official Jekyll Documentation.

Backwards compatibility

This Gem is fully backwards compatible with the old paginator GEM (V1) jekyll-paginate and can be used as a zero-configuration replacement for it. If the old site config is detected then the gem will fall back to the old logic of pagination.

Beware, you cannot run both the new pagination logic from jekyll-paginate-v2 gem and the old one (jekyll-paginate gem) at the same time.

The following _config.yml settings are honored when running this gem in compatability mode

paginate:         8
paginate_path:    '/legacy/page:num/'

See more about the old style of pagination at the page Jekyll paginate.

Paginating Collections

By default the pagination system only paginates posts. If you only have posts and pages in your site you don’t need to worry about a thing, everything will work as intended without you configuring anything.

However if you use document collections, or would like to, then this pagination Gem offers extensive support for paginating documents in one or more collections at the same time.

Collections are groups of documents that belong together but should not be grouped by date. See more about collections on the blog Ben Balters.

Paginating a single collection

Lets expand on Ben’s collection discussion (linked above). Let’s say that you have hundreds of cupcake pages in your cupcake collection. To create a pagination page for only documents from the cupcake collection you would do this:

---
layout:           page
title:            All Cupcakes
pagination:
  enabled:        true
  collection:     cupcakes
---

Paginating multiple collections

Lets say that you want to create a single pagination page for only small cakes on your page (you have both cupcakes and cookies to sell). You could do that like this

---
layout:           page
title:            Litle bits
pagination:
  enabled:        true
  collection:     cupcakes, cookies
---

The special `all` collection

Now your site has grown and you have multiple cake collections on it and you want to have a single page that paginates all of your collections at the same time. You can use the special all collection name for this.

---
layout:           page
title:            All the Cakes!
pagination:
  enabled:        true
  collection:     all
---

Due to the all keyword being reserved for this feature, you cannot have a collection called all in your site configuration. Sorry.

Paginate categories, tags, locales

Enabling pagination for specific categories, tags or locales is as simple as adding values to the pagination page front-matter and corresponding values in the posts.

Filtering categories

Filter single category 'software'

---
layout:           post
pagination:
  enabled:        true
  category:       software
---

Filter multiple categories - lists only posts belonging to all categories.

pagination:
  enabled:        true
  category:       software, ruby

To define categories you can either specify them in the front matter or through the page variables of your Jekyll site (categories are derived from the directory structure above the _posts directory). You can actually use both approaches to assign your pages to multiple categories.

Filtering tags

Filter on a single tag

pagination:
  enabled:        true
  tag:            cool

Filter on multiple tags

pagination:
  enabled:        true
  tag:            cool, life

When specifying tags in your posts make sure that the values are not enclosed in single quotes (double quotes are fine). If they are you will get a cryptic error when generating your site that looks like

Error: could not read file : did not find expected key while parsing a block
mapping at line 2 column 1

Filtering locales

In the case your site offers multiple languages you can include a locale item in your post front matter. The paginator can then use this value to filter on. The category page front-matter would look like this:

pagination:
  enabled:        true
  locale:         en_US

Then for the relevant posts, include the locale variable in their front-matter

locale:           en_US

Paginate on combination of filters

Including only posts from categories ruby and software written in English language.

pagination:
  enabled:        true
  category:       software, ruby
  locale:         en_US, en_GB, en_WW

Only showing posts tagged with cool and in category cars

pagination:
  enabled:        true
  category:       cars
  tag:            cool

and so on and so on.

Configuration overrides

All of the configuration elements from the _config.yml file can be overwritten in the pagination pages. E.g. if you want one category page to have different permalink structure simply override the item like so

pagination:
  enabled:        true
  category:       cars
  permalink:      '/cars/:num/'

Overriding sorting to sort by the post title in ascending order for another paginated page could be done like so:

pagination:
  enabled:        true
  category:       ruby
  sort_field:     title
  sort_reverse:   false

Advanced Sorting

Sorting can be done by any field that is available in the post front-matter. You can even sort by nested fields. When sorting by nested fields, separate the fields with a colon : character.

As an example, assuming all your posts have the following front-matter:

---
layout: post
author:
  name:
    first:        John
    last:         Smith
  born:           1960
---

You can define pagination sorting on the nested first field like so:

---
layout:           page
title:            Authors by first name
pagination:
  enabled:        true
  sort_field:     'author:name:first'
---

To sort by the born year in decending order (youngest first)

---
layout:           page
title:            Authors by birth year
pagination:
  enabled:        true
  sort_field:     'author:born'
  sort_reverse:   true
---

Creating Pagination Trails

Creating a trail structure for your pagination as shown above can be achieved by enabling the trail configuration and including a little extra code in your liquid templates.

pagination:
  trail:
    before:       2 # The number of links before the current page
    after:        2  # The number of links after the current page

Your layout file would then have to include code similar to the following to generate the correct HTML structure:

{% if paginator.page_trail %}
  {% for trail in paginator.page_trail %}
    <li {% if page.url == trail.path %}class="selected"{% endif %}>
      <a href="{{ trail.path | prepend: site.baseurl }}" title="{{trail.title}}">
        {{ trail.num }}
      </a>
    </li>
  {% endfor %}
{% endif %}

See example3 for a demo of a pagination trail.

The trail object exposes three properties:

num: The number of the page
path: The path to the page
title: The title of the page

The algorithm will always attempt to keep the same trail length for all pages (trail length = before + after + 1). As an example if we have only 7 pagination pages in total and the user is currently on page 6 then the trail would look like this.

Different number of before and after trail links can be specified. Below is an example of how the yml config below would look like when on the same page 4:

pagination:
  trail:
    before:       1
    after:        3

Detecting pagination pages

To identify the auto-generated pages that are created by the pagination logic when iterating through collections such as site.pages the page.autogen variable can be used like this:

{% for my_page in site.pages %}
  {% if my_page.title and my_page.autogen == nil %}
    <h1>{{ my_page.title | escape }}</h1>
  {% endif %}
{% endfor %}

In this example only pages that have a title and are not auto-generated are included. This variable is created and assigned the value:

page.autogen = "jekyll-paginate-v2"

by the pagination logic. This way you can detect which pages are auto-generated and by what gem.

Formatting page titles

The title field in both the site.config and the front-matter configuration supports the following macros.

Table 2. Paginator object field macros
Macro	Replaced by	Example
`:title`	original page title	Page with `title: "Index"` and paginate config `title: ":title - split"` becomes `<title>Index - split</title>`
`:num`	number of the current page	Page with `title: "Index"` and paginate config `title: ":title (page :num)"` the second page becomes `<title>Index (page 2)</title>`
`:max`	total number of pages	Page with paginate config `title: ":num of :max"` the third page of 10 will become `<title>3 of 10</title>"`

Reading pagination meta data

Each pagination page defines an information structure pagination_info that is available to the liquid templates. This structure contains meta information for the pagination process, such as current pagination page and the total number of paginated pages.

The following fields are available:

Table 3. Paginator object `pagination_info`
Field	Description
`curr_page`	The number of the current pagination page
`total_pages`	The total number of pages in this pagination

See below an example on how to print out a "Page x of n" in the pagination layout:

<h2>Page {{page.pagination_info.curr_page}} of {{page.pagination_info.total_pages}}</h2>