Pagination

By Amr

Implement previous/next navigation buttons and paginated post lists in your Jekyll site.

Estimated reading time: 3 minutes

• Share on Reddit
• Share on LinkedIn
• Share on Twitter

• ---

• Page Improvements

• Improve Page Polish content, structure, and presentation of this page
• Expand Page Add depth, examples, and missing sections to this page
• Update Page Refresh outdated content, versions, links, and screenshots
• Fix Page Issue Report a typo, broken link, layout glitch, or content bug
• SEO Optimize Improve discoverability, metadata, and structured data
• Accessibility Audit Audit this page for WCAG 2.1 AA compliance

• ---

• Site Improvements

• UI/UX Improvement Propose a design or UX refinement for the theme
• New Feature Propose a new site-wide feature or capability
• Component Enhancement Improve a Jekyll layout, include, or shared component
• Performance Optimization Improve load time, Core Web Vitals, and asset delivery

Edit on GitHub

Table of Contents

Pagination

Add pagination buttons for navigating between pages and posts.

Overview

Pagination provides convenience for users navigating through content. This guide covers:

1. Previous/Next buttons for posts
2. Paginated post lists
3. Keyboard shortcuts for navigation

Previous/Next Navigation

Basic Implementation

Create _includes/pagination.html:

<ul class="pager">
  {% if page.previous.url %}
    <li><a class="btn btn-outline-primary" href="{{page.previous.url}}">Previous</a></li>
  {% else %}
    <li class="disable"><a class="btn btn-outline-primary disabled">Previous</a></li>
  {% endif %}
  {% if page.next.url %}
    <li class="next"><a class="btn btn-outline-primary" href="{{page.next.url}}">Next</a></li>
  {% else %}
    <li class="next disable"><a class="btn btn-outline-primary disabled">Next</a></li>
  {% endif %}
</ul>

Include in Your Layout

Add to your template (e.g., _layouts/journals.html):

{% include pagination.html %}
<hr />
<div class="post">{{ content }}</div>
<hr />
{% include pagination.html %}

Custom Sort Order

Sort by a custom field (like index) instead of date:

{% if page.collection %}
  {% assign posts = site[page.collection] | sort: 'index' %}
  {% for links in posts %}
    {% if links.title == page.title %}
      {% unless forloop.first %}
        {% assign prevurl = prev.url %}
      {% endunless %}
      {% unless forloop.last %}
        {% assign next = posts[forloop.index] %}
        {% assign nexturl = next.url %}
      {% endunless %}
    {% endif %}
    {% assign prev = links %}
  {% endfor %}

  <ul class="pager">
    {% if prevurl %}
      <li><a class="btn btn-outline-primary" href="{{prevurl}}">Previous</a></li>
    {% else %}
      <li class="disable"><a class="btn btn-outline-primary disabled">Previous</a></li>
    {% endif %}
    {% if nexturl %}
      <li class="next"><a class="btn btn-outline-primary" href="{{nexturl}}">Next</a></li>
    {% else %}
      <li class="next disable"><a class="btn btn-outline-primary disabled">Next</a></li>
    {% endif %}
  </ul>
{% endif %}

Keyboard Navigation

Add keyboard shortcuts for arrow key navigation:

<script>
document.body.onkeyup = function(e){
  if (e.keyCode == '37') { window.location = '{{prevurl}}'; }
  if (e.keyCode == '39') { window.location = '{{nexturl}}'; }
};
</script>

This allows users to press ← and → arrow keys to navigate.

Paginated Post Lists

For paginating a list of posts, use the jekyll-paginate plugin:

Configuration

# _config.yml
plugins:
  - jekyll-paginate

paginate: 10
paginate_path: "/blog/page:num/"

Template

{% for post in paginator.posts %}
  <article>
    <h2><a href="{{ post.url }}">{{ post.title }}</a></h2>
    <p>{{ post.excerpt }}</p>
  </article>
{% endfor %}

<!-- Pagination Links -->
<nav>
  {% if paginator.previous_page %}
    <a href="{{ paginator.previous_page_path }}">← Newer</a>
  {% endif %}
  
  <span>Page {{ paginator.page }} of {{ paginator.total_pages }}</span>
  
  {% if paginator.next_page %}
    <a href="{{ paginator.next_page_path }}">Older →</a>
  {% endif %}
</nav>

Styling

Add CSS for pagination buttons:

.pager {
  display: flex;
  justify-content: space-between;
  list-style: none;
  padding: 0;
  margin: 2rem 0;
}

.pager li.disable a {
  pointer-events: none;
  opacity: 0.5;
}

.pager .next {
  margin-left: auto;
}

Reference

• Jekyll Pagination Documentation
• Previous/Next Links in Collections

See also

• [[Jekyll]]
• [[Liquid]]
• [[front-matter]]