How to Add Pagination to Your Jekyll Blog

By default, Jekyll lists all your posts on a single page. Once you have 20+ posts, that page becomes slow and hard to navigate. Pagination splits posts across multiple pages with numbered links — this guide shows you how to set it up properly.

Which Pagination Plugin to Use

Jekyll has two pagination plugins:

jekyll-paginate — the original, simple, but limited. Only works on index.html, only paginates posts. Officially deprecated but still available.

jekyll-paginate-v2 — the modern replacement. Works on any page, paginates posts, collections, or filtered sets. This is what you should use.

Setting Up jekyll-paginate-v2

Step 1: Install

# Gemfile
gem "jekyll-paginate-v2"

# _config.yml
plugins:
  - jekyll-paginate-v2

pagination:
  enabled: true
  per_page: 10
  permalink: '/page/:num/'
  title: ':title - Page :num'
  limit: 0        # 0 = no limit
  sort_field: 'date'
  sort_reverse: true

Run bundle install.

Step 2: Enable Pagination on Your Index Page

In your blog index page (e.g. index.html or blog.md), add pagination to the front matter:

---
layout: home
title: Blog
pagination:
  enabled: true
---

Step 3: Update Your Template to Use paginator

In your home layout (_layouts/home.html):

{% if paginator.posts %}
  {% assign posts = paginator.posts %}
{% else %}
  {% assign posts = site.posts %}
{% endif %}

{% for post in posts %}
  <article class="post-card">
    <a href="{{ post.url }}">
      <h2>{{ post.title }}</h2>
    </a>
    <time>{{ post.date | date: "%B %d, %Y" }}</time>
    <p>{{ post.excerpt | strip_html | truncatewords: 30 }}</p>
    <a href="{{ post.url }}">Read more →</a>
  </article>
{% endfor %}

{% include pagination.html %}

Step 4: Create the Pagination Include

Create _includes/pagination.html:

{% if paginator.total_pages > 1 %}
<nav class="pagination" aria-label="Blog pagination">
  {% if paginator.previous_page %}
    <a href="{{ paginator.previous_page_path }}" class="pagination__prev" aria-label="Previous page">
      ← Newer
    </a>
  {% else %}
    <span class="pagination__prev pagination__prev--disabled">← Newer</span>
  {% endif %}

  <span class="pagination__info">
    Page {{ paginator.page }} of {{ paginator.total_pages }}
  </span>

  {% if paginator.next_page %}
    <a href="{{ paginator.next_page_path }}" class="pagination__next" aria-label="Next page">
      Older →
    </a>
  {% else %}
    <span class="pagination__next pagination__next--disabled">Older →</span>
  {% endif %}
</nav>
{% endif %}

Step 5: Style the Pagination

// _sass/_pagination.scss
.pagination {
  display: flex;
  align-items: center;
  justify-content: center;
  gap: 1rem;
  margin: 2rem 0;
  font-size: 0.95rem;
}

.pagination__prev,
.pagination__next {
  display: inline-flex;
  align-items: center;
  padding: 0.5rem 1rem;
  border: 1px solid var(--border-color);
  border-radius: 6px;
  color: var(--link-color);
  text-decoration: none;
  transition: background 0.2s;

  &:hover {
    background: var(--card-bg);
  }

  &--disabled {
    color: var(--text-muted);
    cursor: default;
    pointer-events: none;
  }
}

.pagination__info {
  color: var(--text-muted);
  font-size: 0.9rem;
}

Numbered Page Links

For a numbered pagination bar instead of just prev/next:

{% if paginator.total_pages > 1 %}
<nav class="pagination">
  {% if paginator.previous_page %}
    <a href="{{ paginator.previous_page_path }}">←</a>
  {% endif %}

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

  {% if paginator.next_page %}
    <a href="{{ paginator.next_page_path }}">→</a>
  {% endif %}
</nav>
{% endif %}

Paginating a Specific Category

With jekyll-paginate-v2 you can paginate filtered content:

---
layout: category
title: Tutorials
pagination:
  enabled: true
  category: Tutorial
  per_page: 8
---

Now /tutorials/ shows only Tutorial category posts, paginated.

Paginating Collections

You can paginate any collection, not just posts:

---
layout: themes
title: All Themes
pagination:
  enabled: true
  collection: themes
  per_page: 12
---

Common Pagination Problems

“Pagination does not work” on GitHub Pages

jekyll-paginate-v2 is not on GitHub Pages’ allowed plugin list. You need to use GitHub Actions for the build:

# .github/workflows/deploy.yml
- name: Build Jekyll
  run: bundle exec jekyll build
  env:
    JEKYLL_ENV: production

Paginated pages 404

Check that your permalink in _config.yml matches what you expect. The default is /page/:num/, so page 2 is at /page/2/.

Only page 1 exists

Make sure pagination: enabled: true is in both _config.yml (global) and the page’s front matter.

Pagination is built into many Jekyll themes on JekyllHub — look for themes with “blog” in the features list.

jekyll pagination jekyll paginate jekyll blog pagination