Skip to main content
Documentation Writing Content Resources

Pagination

Pagination support is built-in to Bridgetown, but it is not enabled by default. You can enable it in the config file using:

pagination:
  enabled: true

Page Configuration #

To facilitate pagination on any given page (like index.html, blog.md, etc.) 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

Attributes for Defining Pagination #

Variable Description

collection

Required The collection to paginate

offset

Default: 0 Supports skipping x number of posts from the beginning of the post list

per_page

Default 10 Number of resources per page

permalink

Default: "/page/:num/" Supports :num as customizable elements

title

Default: ":title (Page :num)" Supports :num customizable elements

sort_reverse

Default: true Sorts the posts in reverse order

sort_field

Default: "date" Sorts the posts by the specified field

limit

Default: 0 Limits how many content objects to paginate (default: 0, means all)

debug

Default: false Turns on debug output for the gem

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, 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

first_page_path

Returns the path to the first page, or nil if none

last_page

The number of the last page, or nil if none

last_page_path

Returns the path to the last page, or nil if none

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 previous page exists

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

Back to Resources