对于很多网站来说，尤其是对于博客，我们很常见的将我们的posts的很长的列表分成多个小的列表并分多页进行展示。Jekyll有内置的分页，我们可以自行为分页的列表产生合适的文件和目录。

分页只能适用于HTML文件

Jekyll的分页并不适用于Jekyll网站中的Markdown或者Textile的文件，只适用于HTML文件。一般我们都是使用分页来展示posts，因此这个问题基本没有影响。

开启分页(Enable pagination)

在博客中开启分页功能需要在_config.yml文件中指定每页需要显示的项数：

paginate: 5

这个项数就是每页显示的posts的最大数目。

可以指定分页的页面放置的目标位置：

paginate_path: "blog/page:num"

这里:num是分页的页号，从2开始。Jekyll会将首页写到blog/index.html中，将每个分页作为paginator并写到blog/page:num中。如果网站有12篇文章(posts)，指定paginate:5，Jekyll就会将开始的5篇写到blog/index.html中，之后的5篇写到blog/page2/index.html中，最后的2篇写到blog/page3/index.html中。

可用的Liquid属性

分页插件提供的paginatorliquid对象有以下属性：

属性	描述
page	当前页数
per_page	每页文章数量
posts	当前页面中文章的列表
total_posts	网站中所有文章的数目
total_pages	所有分页的页数
previous_page	前一个分页的页号，如果前面没有分页就是nil
previous_page_path	上一个分页的路径，如果没有就是nil
next_page	下一个分页的页号，如果前面没有分页就是nil
next_page_path	下一个分页的路径，如果没有就是nil

分页不支持标签(tags)和类别(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)

下一步要做的就是使用paginator变量来真正的展示你的文章列表，一般我们会在网站主页面的其中一页来显示文章列表。下面是一个简单的将分页的文章render到一个HTML文件中的例子：

---
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="/page{{ paginator.previous_page }}" 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="/page{{ paginator.next_page }}" class="next">Next</a>
  {% else %}
    <span class="next ">Next</span>
  {% endif %}
</div>

!!注意页号为1的边界条件

Jekyll不会产生‘page1’的目录，所以上面的代码在/page1链接产生后不起作用。可以参考下面的方法处理这个问题。

下面的HTML代码片段处理了第一页的情况，同时提供了除了当前页的其他所有页面的链接列表。

{% 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="{{ '/index.html' | 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 %}

PS:

文章翻译自jekyll官方文档(2013-10-11)：

Permalinks

Jekyll文档(十一) -- Pagination