Rubyists Assemble! We're currently raising funds to help drive the launch of 1.0! Join the effort today ▸

Pagination

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

paginator.page

The number of the current page

paginator.per_page

Number of posts per page

paginator.resources

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

paginator.total_resources

Total number of resources

paginator.total_pages

Total number of paginated pages

paginator.previous_page

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

paginator.previous_page_path

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

paginator.next_page

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

paginator.next_page_path

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

Back to Posts