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 offers a pagination plugin, so you can automatically generate the appropriate files and folders you need for paginated listings.
For Jekyll 3, include the jekyll-paginate
plugin in your Gemfile and in your _config.yml
under plugins
. For Jekyll 2, this is standard.
Pagination only works within HTML files
Pagination does not work from within Markdown or Textile files from your Jekyll site. Pagination works when called from within the HTML file, named
index.html
, which optionally may reside in and produce pagination from within a subdirectory, via thepaginate_path
configuration value.
To enable pagination for posts on your blog, add a line to the _config.yml
file that specifies how many items should be displayed per page:
paginate: 5
The number should be the maximum number of Posts you’d like to be displayed per-page in the generated site.
You may also specify the destination of the pagination pages:
paginate_path: "/blog/page:num/"
This will read in blog/index.html
, send it each pagination page in Liquid as paginator
and write the output to blog/page:num/
, where :num
is the pagination page number, starting with 2
. If a site has 12 posts and specifies paginate: 5
, Jekyll will write blog/index.html
with the first 5 posts, blog/page2/index.html
with the next 5 posts and blog/page3/index.html
with the last 2 posts into the destination directory.
Don't set a permalink
Setting a permalink in the front matter of your blog page will cause pagination to break. Just omit the permalink.
Pagination for categories, tags and collections
The more recent jekyll-paginate-v2 plugin supports more features. See the pagination examples in the repository. This plugin is not supported by GitHub Pages.
The pagination plugin exposes the paginator
liquid object with the following attributes:
Attribute | Description |
---|---|
| current page number |
| number of posts per page |
| a list of posts for the current page |
| total number of posts in the site |
| number of pagination pages |
| page number of the previous pagination page, or |
| path of previous pagination page, or |
| page number of the next pagination page, or |
| path of next pagination page, or |
Pagination does not support tags or categories
Pagination pages through every post in the
posts
variable unless a post hashidden: true
in its YAML Front Matter. It does not currently allow paging over groups of posts linked by a common tag or category. It cannot include any collection of documents because it is restricted to 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:
--- 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="{{ paginator.previous_page_path }}" 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="{{ paginator.next_page_path }}" class="next">Next</a> {% else %} <span class="next ">Next</span> {% endif %} </div>
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.
{% if paginator.total_pages > 1 %} <div class="pagination"> {% if paginator.previous_page %} <a href="{{ paginator.previous_page_path | prepend: site.baseurl | replace: '//', '/' }}">« Prev</a> {% else %} <span>« 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 »</a> {% else %} <span>Next »</span> {% endif %} </div> {% endif %}
© 2008–2018 Tom Preston-Werner and Jekyll contributors
Licensed under the MIT license.
https://jekyllrb.com/docs/pagination/