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


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

  enabled: true

to your config file.

Page Configuration

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

layout: page
  collection: posts

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

{% for post in paginator.resources %}
  <h1>{{ }}</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:

  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:

  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 %}
      <a href="{{ paginator.previous_page_path }}">Previous Page</a>
    {% endif %}
    {% if paginator.next_page %}
      <a href="{{ paginator.next_page_path }}">Next Page</a>
    {% endif %}
{% endif %}

Liquid Attributes Available

The paginator Liquid object provides the following attributes:

Variable Description

The number of the current page


Number of posts per page


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


Total number of resources


Total number of paginated pages


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


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


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


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

Back to Posts