Pagebreak is an open-source tool for implementing pagination on any static website output. It is tooling agnostic, and chains onto the end of a complete static site build.
The primary goal of Pagebreak is to decouple pagination logic from templating. Using Pagebreak means you can:
- Configure pagination within a portable component, and paginate whatever page that component winds up on.
- Render components in a component browser, (e.g. with Storybook or Bookshop), without having to mock pagination tags.
- Have editors configure pagination settings on a per-component basis.
To paginate a section on your website, add the data-pagebreak tag to the container element, and specify how many items you want per page. Then, in your static site generator of choice, output all items onto the page.
<section data-pagebreak="2">
<article>Item 1</article>
<article>Item 2</article>
<article>Item 3</article>
</section>Pagebreak will then pick this up, and split the monolithic file into as many pages as needed.
By default, for a given dist/index.html file, Pagebreak will output pages like the following: dist/page/2/index.html
You can customise this url with the data-pagebreak-url tag:
<section
data-pagebreak="1"
data-pagebreak-url="./archive/page-:num/" >
<article>Item 1</article>
<article>Item 2</article>
<article>Item 3</article>
</section>For a given dist/index.html file, this would output:
- Page 1:
dist/index.html - Page 2:
dist/archive/page-2/index.html - Page 3:
dist/archive/page-3/index.html
The url will be resolved relative to the html file that is being paginated.
By default, Pagebreak will update the <title> element on paginated pages, as well as the og:title and twitter:title meta elements. For a given title "Blog", the default page titles will be of the form "Blog | Page 2".
You can customise this title with the data-pagebreak-meta tag:
<head>
<title>Blog</title>
</head>
<body>
<section
data-pagebreak="1"
data-pagebreak-meta=":content Page #:num">
<article>Item 1</article>
<article>Item 2</article>
</section>
</body>With the above example, page 2 would now contain <title>Blog Page #2</title>. The first page will always remain unchanged.
Pagination controls are implemented with the data-pagebreak-control attribute.
Next and previous links can be inserted with the prev and next controls.
<a data-pagebreak-control="prev">Newer Items</a>
<a data-pagebreak-control="next">Older Items</a>Pagebreak will pick these up and update the URLs to link each page to its siblings. In the instance where there is no next or previous page, the element will be removed from the page.
If you want to toggle behavior when a next or previous page doesn't exist, you can use the !prev and !next controls.
<span data-pagebreak-control="!prev">No Previous Page</span>
<span data-pagebreak-control="!next">No Next Page</span>These elements will be removed from the page if their respective pages exist.
If you want to show current and total page counts, you can use the current and total controls.
<p>
Page
<span data-pagebreak-label="current">1</span>
of
<span data-pagebreak-label="total">1</span>
</p>Given an items/index.html file:
<section
data-pagebreak="2"
data-pagebreak-url="./page/:num/archive/" >
<article>Item 1</article>
<article>Item 2</article>
<article>Item 3</article>
<article>Item 4</article>
<article>Item 5</article>
</section>
<a href="" data-pagebreak-control="prev">Previous</a>
<a href="" data-pagebreak-control="next">Next</a>The new items/index.html will look like:
<section>
<article>Item 1</article>
<article>Item 2</article>
</section>
<a href="./page/2/archive/">Next</a>And items/page/2/archive/index.html will look like:
<section>
<article>Item 3</article>
<article>Item 4</article>
</section>
<a href="../../../">Previous</a>
<a href="../../3/archive/">Next</a>If you have NodeJS installed, the easiest way to run pagebreak is via npx:
npx @pagebreak/cli -s _site -o _site
This wrapper package handles downloading the correct binary release for your platform and executing it. Distributing pagebreak in this way allows it to integrate with any static SSG.
If your site is hosted on CloudCannon, add a .cloudcannon/postbuild script to your repo containing the npx script. For other platforms, add the npx command in the correct spot to run a build hook.
Alternatively, you can change the build command for your site. For example:
# Jekyll
bundle exec jekyll build && npx @pagebreak/cli -s _site -o _site
# Hugo
hugo && npx @pagebreak/cli -s public -o publicPagebreak is also made available as a portable binary, and you can download the latest release for your platform here on GitHub.
When used as a CLI, the flags are:
| Flag | Short | Description |
|---|---|---|
source |
s |
Location of a built static website |
output |
o |
Location to output the paginated website |
For example:
$: ./pagebreak -s _site -o _site
would paginate a website in-place (updating the source files)