Skip to main content
Documentation Writing Content Resources

Pagination

Help Needed! This Documentation page is in need of review and possible revision. Can you help us out?
We’d greatly appreciate it! 😃👍

Pagination support is built-in to Bridgetown, but it is not enabled by default. To enable it on your site, simply add:

pagination:
  enabled: true

to your config file.

Page Configuration #

To facilitate pagination on any given page (like index.html, blog.md, etc.) then simply include configuration in the resource’s front matter to specify which collection you’d like to paginate through:

---
layout: page
paginate:
  collection: posts
---

Then you can use the paginator.resources logic to iterate through the collection’s resources.

{% for post in paginator.resources %}
  <h1>{{ post.data.title }}</h1>
{% endfor %}

By default, paginated pages will have 10 items per page. You can change this in your config by modifying the per_page key like so:

paginate:
  collection: posts
  per_page: 4

You can also control the sort field and order of the paginated result set separately from the default sort of the collection:

paginate:
  collection: movies
  sort_field: rating
  sort_reverse: true

Excluding a Resource from the Paginator #

You can exclude a resource from being included in the paginated items list.

exclude_from_pagination: true

To display pagination links, simply use the paginator Liquid object as follows:

{% if paginator.total_pages > 1 %}
  <ul class="pagination">
    {% if paginator.previous_page %}
    <li>
      <a href="{{ paginator.previous_page_path }}">Previous Page</a>
    </li>
    {% endif %}
    {% if paginator.next_page %}
    <li>
      <a href="{{ paginator.next_page_path }}">Next Page</a>
    </li>
    {% endif %}
  </ul>
{% endif %}

Liquid Attributes Available #

The paginator Liquid object provides the following attributes:

Variable Description

page

The number of the current page

per_page

Number of resources per page

resources

Resources (aka posts, etc.) available for the current page

total_resources

Total number of resources

total_pages

Total number of paginated pages

previous_page

The number of the previous page, or nil if no previous page exists

previous_page_path

The path to the previous page, or nil if no previous page exists

next_page

The number of the next page, or nil if no subsequent page exists

next_page_path

The path to the next page, or nil if no subsequent page exists

Back to Resources