Pagination

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

Ruby

YAML (Legacy)

# within Bridgetown.configure do |config| block
pagination do
  enabled true
end

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.

ERB

Liquid

# for earlier versions paginator.resources.each
<% paginator.each do |post| %>
  <h1>%= post.data.title %></h1>
<% end %>

{% 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 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 via its front matter.

exclude_from_pagination: true

Pagination Links #

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

ERB

Liquid

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

{% 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 %}

Properties Available #

The paginator Ruby / Liquid object provides the following properties:

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

Considerations When Using Pagination #

On paginated pages, the originating collection is replaced by the paginator. Code in a layout like resource.collection.label will generate undefined method errors on your paginated page. Accessing the collection directly rather than through the paginator will also fail.

Back to Resources