列表分页 Pagination

很多网站，特别是博客，经常会将文章列表以每10篇文章一页进行分页。Jekyll 提供了一个叫做“分页”的插件，它可以自动帮你生成创建这些分页列表所需的文件和文件夹。

对于 Jekyll 3 及更高版本，需要在 Gemfile 和 _config.yml 的 plugins 配置项中添加 jekyll-paginate 插件。对于 Jekyll 2，该插件已默认包含。

分页仅适用于 HTML 文件

Jekyll 的分页功能无法在 Markdown 文件中使用。仅当从 HTML 文件（如 index.html）中调用时，分页功能才能生效。该文件可以位于子目录中，并通过 paginate_path 配置项控制分页路径。

启用分页

要在博客的文章列表中启用分页，需要在 _config.yml 文件中添加一行，指定每页显示的文章数量：

paginate: 10

这个数值代表生成的网站中，每页最多显示的文章数量。

还可以指定分页页面的路径：

paginate_path: "/blog/page:num/"

Jekyll 会读取 blog/index.html，在 Liquid 变量 paginator 中传递分页信息，并将输出写入 blog/page:num/，其中 :num 为分页页码，从 2 开始。
例如，如果站点有 22 篇文章，并且 paginate: 10，Jekyll 将生成：

blog/index.html，包含前 10 篇文章；
blog/page2/index.html，包含接下来的 10 篇文章；
blog/page3/index.html，包含最后 2 篇文章。

不要设置 permalink

在博客首页的 front matter 中设置 permalink 会导致分页失效。请省略 permalink 配置。

分类、标签和集合的分页

更先进的 jekyll-paginate-v2 插件支持更多功能。详情请参考该插件仓库中的分页示例。 注意：此插件不被 GitHub Pages 支持。

可用的 Liquid 属性

分页插件公开了 paginator Liquid 对象，其属性如下：

Variable	Description
`paginator.page`	当前页码
`paginator.per_page`	每页的文章数量
`paginator.posts`	当前页面的文章
`paginator.total_posts`	文章总数
`paginator.total_pages`	总页数
`paginator.previous_page`	上一页的页码，如果没有上一页，则为 `nil`
`paginator.previous_page_path`	上一页的路径，如果没有上一页，则为 `nil`
`paginator.next_page`	下一页的页码，如果没有下一页，则为 `nil`
`paginator.next_page_path`	下一页的路径，如果没有下一页，则为 `nil`

分页不支持标签或分类

分页功能默认遍历 posts 变量中的所有文章，除非文章在 Front Matter 中设置了 hidden: true。目前，分页功能不支持按标签或分类分页，也不能用于包含非文章的集合（collections），仅适用于博客文章`post`。

渲染并生成文章列表分页

现在，你需要在页面上展示分页文章列表。Jekyll 会把 paginator 变量传递到你的页面，你可以用它来显示当前页的文章，并添加分页导航。下面是一个简单的示例就，可以在 HTML 文件中使用以下代码：

---
layout: default
title: 我的博客
---

<!-- 遍历当前页的文章 -->
{% 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="{{ paginator.previous_page_path }}" class="previous">
      上一页
    </a>
  {% else %}
    <span class="previous">上一页</span>
  {% endif %}
  <span class="page_number ">
    第 {{ paginator.page }} 页，共 {{ paginator.total_pages }} 页
  </span>
  {% if paginator.next_page %}
    <a href="{{ paginator.next_page_path }}" class="next">下一页</a>
  {% else %}
    <span class="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 | relative_url }}">&laquo; 上一页</a>
  {% else %}
    <span>&laquo; 上一页</span>
  {% endif %}

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

  {% if paginator.next_page %}
    <a href="{{ paginator.next_page_path | relative_url }}">下一页 &raquo;</a>
  {% else %}
    <span>下一页 &raquo;</span>
  {% endif %}
</div>
{% endif %}

这样，无论你有多少页，分页导航都会正确显示，第一页也不会生成错误的 /page1/ 链接。