jekyll/site/_posts/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 post 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 probably won’t be an issue.

Enable pagination

The first thing you need to do to enable pagination for your blog is add a line to the _config.yml Jekyll configuration file that specifies how many items should be displayed per page. Here is what the line should look like:

{% 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.

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 %}

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 " }}%}

{% 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 %}

{{ "{% 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 " }}%}

<a href="/page{{ "{{paginator.next_page" }}}}">Next

{{ "{% else " }}%}

Next

{{ "{% endif " }}%}

{% endhighlight %}