Jekyll::Paginator

Default pagination generator for Jekyll.

Installation

Add this line to your application's Gemfile:

gem 'jekyll-paginator'

And then execute:

$ bundle

Or install it yourself as:

$ gem install jekyll-paginator

Usage

With many websites — especially blogs — it’s very common to break the main listing of posts up into smaller lists and display them over multiple pages. Jekyll offers a pagination plugin, so you can automatically generate the appropriate files and folders you need for paginated listings.

For Jekyll 3, include the jekyll-paginator plugin in your Gemfile and in your _config.yml under plugins. For Jekyll 2, this is under gems.

Enable pagination

To enable pagination for your blog, add a line to the _config.yml file that specifies how many items should be displayed per page:

paginate: 5

The number should be the maximum number of Posts you’d like to be displayed per-page in the generated site.

You may also specify the destination of the pagination pages:

paginate_path: "/blog/page:num/"

Note: The above mentioned syntax belongs to jekyll-paginate gem, so the following deprecation warnings you will see:

Deprecation: You appear to have pagination turned on, but you haven't included the `jekyll-paginate` gem. 
Ensure you have `plugins: [jekyll-paginate]` in your configuration file."

This will read in blog/index.html, send it each pagination page in Liquid as paginator and write the output to blog/page:num/, where :num is the pagination page number, starting with 2. If a site has 12 posts and specifies paginate: 5, Jekyll will write blog/index.html with the first 5 posts, blog/page2/index.html with the next 5 posts and blog/page3/index.html with the last 2 posts into the destination directory.

Enable pagination for multiple pages

If you have a need to have pagination in multiple pages like:

You have a blog page where you are trying to display a paginated list of blog-posts. And, underneath every post title you would like to show article-excerpt(summary from first paragraph normally). You also felt that this could be more verbose so you though to have a more slimmer version of post-list; where there will be only post-title and published/updated date.

In short you want to have two versions/templates for pagination. This is how you can achieve:-

  # in _config.yml
  
  paginate:         2 # default for all below; will be overridden by `per_page` value
  pagination: 
    - paginate:
        path:       /blog/page:num/
        per_page:   2
    - paginate:
        path:       /slim/page:num/
        per_page:   1

Example:

Example Repo:

Liquid Attributes Available

The pagination plugin exposes the paginator liquid object with the following attributes:

Render the paginated Posts

The next thing you need to do is to actually display your posts in a list using the paginator variable that will now be available to you. You’ll probably want to do this in one of the main pages of your site. Here’s one example of a simple way of rendering paginated Posts in a HTML file:

{% raw %}
---
layout: default
title: My Blog
---

<!-- This loops through the paginated posts -->
{% for post in paginator.posts %}
  <h1><a href="{{ post.url }}">{{ post.title }}</a></h1>
  <p class="author">
    <span class="date">{{ post.date }}</span>
  </p>
  <div class="content">
    {{ post.content }}
  </div>
{% endfor %}

<!-- Pagination links -->
<div class="pagination">
  {% if paginator.previous_page %}
    <a href="{{ paginator.previous_page_path }}" class="previous">Previous</a>
  {% else %}
    <span class="previous">Previous</span>
  {% endif %}
  <span class="page_number ">Page: {{ paginator.page }} of {{ paginator.total_pages }}</span>
  {% if paginator.next_page %}
    <a href="{{ paginator.next_page_path }}" class="next">Next</a>
  {% else %}
    <span class="next ">Next</span>
  {% endif %}
</div>
{% endraw %}

The following HTML snippet should handle page one, and render a list of each page with links to all but the current page.

{% raw %}
{% if paginator.total_pages > 1 %}
<div class="pagination">
  {% if paginator.previous_page %}
    <a href="{{ paginator.previous_page_path | prepend: site.baseurl | replace: '//', '/' }}">&laquo; Prev</a>
  {% else %}
    <span>&laquo; Prev</span>
  {% endif %}

  {% for page in (1..paginator.total_pages) %}
    {% if page == paginator.page %}
      <em>{{ page }}</em>
    {% elsif page == 1 %}
      <a href="{{ paginator.previous_page_path | prepend: site.baseurl | replace: '//', '/' }}">{{ page }}</a>
    {% else %}
      <a href="{{ site.paginate_path | prepend: site.baseurl | replace: '//', '/' | replace: ':num', page }}">{{ page }}</a>
    {% endif %}
  {% endfor %}

  {% if paginator.next_page %}
    <a href="{{ paginator.next_page_path | prepend: site.baseurl | replace: '//', '/' }}">Next &raquo;</a>
  {% else %}
    <span>Next &raquo;</span>
  {% endif %}
</div>
{% endif %}
{% endraw %}