Back to Posts

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 a page (like index.html, blog.md, etc.) then simply include configuration in the page’s front matter:

---
layout: page
pagination:
  enabled: true
---

Then you can use the paginator.documents logic to iterate through the documents.

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

Normally the paginated documents are of a Post type, but to load a specific Collection type, just add a collection key like so:

pagination:
  enabled: true
  collection: tigers

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

pagination:
  enabled: true
  per_page: 4

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.documents

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

paginator.total_documents

Total number of documents

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