Implementing Pagination with Pagebreak on an Eleventy Site

Implementing Pagination with Pagebreak on an Eleventy Site

Pagebreak is an open-source tool that simplifies the process of implementing pagination on static websites, including those built with Eleventy. In this article, we'll explore how to integrate Pagebreak into your Eleventy project and take advantage of its pagination features.

Installing Pagebreak

The easiest way to run Pagebreak is via NPX, which downloads the correct binary release for your platform. You can install it with the following command:

npx @pagebreak/cli -s _site -o _site

This command will paginate the website in-place, updating the source files in the `_site` directory.

Integrating Pagebreak with Eleventy

To integrate Pagebreak with your Eleventy build process, you can add the following code to your `eleventy.js` configuration file:

const { execSync } = require('child_process');

eleventyConfig.on('eleventy.after', () => {
 execSync(`npx @pagebreak/cli -s dist -o dist`, { encoding: 'utf-8' });
});

This code runs the Pagebreak command after the Eleventy build process is complete, paginating the files in the `dist` directory.

Configuring Pagination with Pagebreak

To paginate a section of your website, you can use the `data-pagebreak` attribute on the container element and specify the number of items per page. Eleventy can then output all the items onto the page, and Pagebreak will handle splitting them into separate paginated files.

  <section data-pagebreak="2">
   <article>Item 1</article>
   <article>Item 2</article>
   <article>Item 3</article>
   <article>Item 4</article>
  </section>
  

In the example above, Pagebreak will split the content into two pages, with two articles on each page.

Pagination Navigation Controls

Pagebreak provides several controls for rendering pagination navigation elements, such as next/previous links and page numbers. These controls are implemented using the `data-pagebreak-control` attribute.

  <a data-pagebreak-control="prev">Previous</a>
  <a data-pagebreak-control="next">Next</a>
  
  <p>
   Page
   <span data-pagebreak-label="current">1</span>
   of
   <span data-pagebreak-label="total">1</span>
  </p>
  

Pagebreak will update the URLs and content of these elements based on the current page and the total number of pages.

By integrating Pagebreak into your Eleventy project, you can streamline the process of implementing pagination on your static website, while maintaining separation of concerns between pagination logic and templating. For the full documentation visit the Pagebreak Github repo.