2012-07-01-pagination.md

layout	title	prev_section	next_section
docs	Pagination	permalinks	plugins

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 has pagination built-in, so you can automatically generate the appropriate files and folders you need for paginated listings.

Pagination only works within HTML files

Pagination does not work with Markdown or Textile files in your Jekyll site. It will only work when used within HTML files. Since you’ll likely be using this for the list of Posts, this shouldn't be an issue.

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:

{% highlight yaml %} paginate: 5 {% endhighlight %}

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

Liquid Attributes Available

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

Attribute	Description
page	current page number
per_page	number of posts per page
posts	a list of posts for the current page
total_posts	total number of posts in the site
total_pages	number of pagination pages
previous_page	page number of the previous pagination page, or nil if no previous page exists
previous_page_path	path of previous pagination page, or nil if no previous page exists
next_page	page number of the next pagination page, or nil if no subsequent page exists
next_page_path	path of next pagination page, or nil if no subsequent page exists

Pagination does not support tags or categories

Pagination pages through every post in the posts variable regardless of variables defined in the YAML Front Matter of each. It does not currently allow paging over groups of posts linked by a common tag or category.

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:

{% highlight html %} {% raw %}

layout: default title: My Blog

{% for post in paginator.posts %}

{{ post.title }}

{{ post.date }}

{{ post.content }}

{% endfor %}

{% if paginator.previous_page %} Previous {% else %} Previous {% endif %} Page: {{ paginator.page }} of {{ paginator.total_pages }} {% if paginator.next_page %} Next {% else %} Next {% endif %}

{% endraw %} {% endhighlight %}

Beware the page one edge-case

Jekyll does not generate a ‘page1’ folder, so the above code will not work when a /page1 link is produced. See below for a way to handle this if it’s a problem for you.

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

{% highlight html %} {% raw %}

{% if paginator.previous_page %}

{% if paginator.previous_page == 1 %} Previous {% else %} Previous {% endif %}

{% else %}

Previous

{% endif %}

• {% if paginator.page == 1 %} 1 {% else %} 1 {% endif %}

{% for count in (2..paginator.total_pages) %}
  <li class="page">
    {% if count == paginator.page %}
      <span class="current-page">{{ count }}</span>
    {% else %}
      <a href="/page{{ count }}">{{ count }}</a>
    {% endif %}
  </li>
{% endfor %}

{% if paginator.next_page %}

Next

{% else %}

Next

{% endif %}

{% endraw %} {% endhighlight %}