Question

对于大多数网站（尤其是博客），当文章越来越多的时候，就会有分页显示文章列表的需求。Jekyll 已经自建分页功能，你只需要根据约定放置文件即可。

在 Jekyll 3 中，需要在 gems 中安装 jekyll-paginate 插件，并添加到你的 Gemfile 和 _config.yml 中。在 Jekyll 2 中，分页是标准功能。

分页功能只支持 HTML 文件

Jekyll 的分页功能不支持 Jekyll site 中的 Markdown 或 Textile 文件。分页功能从名为 index.html 的 HTML 文件中被调用时，才能工作。分页功能是可选的，可能通过 paginate_path 配置的值，驻留和生成在子目录中。

开启分页功能

开启分页功能很简单，只需要在 _config.yml 里边加一行，指明每页该展示多少项目：

paginate: 5

这个数字应当是你希望在生成的站点中每页展示博客数目的最大值。

你可能还需要指定分页页面的目标路径：

paginate_path: "blog/page:num"

blog/index.html 将会读取这个设置，把它传给每个分页页面，然后从第 2 页开始输出到 blog/page:num, :num 是页码。如果有 12 篇文章并且做如下配置 paginate: 5, Jekyll 会将前 5 篇文章写入 blog/index.html，把接下来的 5 篇文章写入 blog/page2/index.html，最后 2 篇写入 blog/page3/index.html。

不要设置 permalink

在你的博客的头信息中设置 permalink 会造成分页功能的瘫痪。缺省设置 permalink 即可。

可用的 Liquid 属性

分页功能插件使得 paginator liquid 对象具有下列属性：

属性	描述
page	当前页码
per_page	每页文章数量
posts	当前页的文章列表
total_posts	总文章数
total_pages	总页数
previous_page	上一页页码 或 nil（如果上一页不存在）
previous_page_path	上一页路径 或 nil（如果上一页不存在）
next_page	下一页页码 或 nil（如果下一页不存在）
next_page_path	下一页路径 或 nil（如果下一页不存在）

不支持对“标签”和“类别”分页

分页功能遍历 posts 下的所有文章，而忽略定义在文章内的头信息中的变量。现在不支持对“标签”和“类别”分页。也不支持任何文件集合，因为该功能被限制在 posts 中。

生成带分页功能的文章

接下来你需要做的事情，就是使用你已经掌握的 paginator 变量，列表展示你的文章。下边是一个简单的例子，在 HTML 文件中生成带分页功能的文章：

---
layout: default
title: My Blog
---

<!-- 遍历分页后的文章 -->
{% 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 %}

<!-- 分页链接 -->
<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>

注意首尾页

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