How to Configure Pagination in Sculpin

documentation December 6th, 2017

If you use Sculpin, the excellent PHP-based static site generator, it may not be obvious as to how to configure pagination. In this article, I'll step through how.

By default, Sculpin's global paginator will render up to ten items per page, if there are at least ten items available to be rendered. If that suits your needs, then you won't need to change the setting. However, if, like me, you need to change the setting, then it's good to know how to do it.

It's something I've meant to do for some time now but never got around to finding out how to do. If you look at the image below, you'll see why.

Sculpin rendering 10 items per page

There are ten records rendered with the tenth trailing off at the end of the page. I've always been one for aesthetics and a professional appearance, so have always felt that having an even set of rows renders better, as in the screenshot below. Much better, don't you think?

Sculpin rendering 12 items per page

So if you're in a similar position, how do you do it? It turns out that it's not that hard at all. All you need to do is add a setting in app/config/sculpin_kernel.yml, which I've included a sample of below.

sculpin_pagination:
    max_per_page: 12

As you can see, there's not much to it. You first define a new configuration section, sculpin_pagination, and then in it set a value for max_per_page. After saving the file, if you run either the generate or publish script, your site will then render up to twelve items per page when paginating records (assuming you've set it to 12).

Configuring Pagination For Individual Content Types

That's how to do it on a global level, what about for individual content types? Good question. Gladly it's straightforward to do.

In the template that you use to render a specific content type, in the YAML front-matter, you can add a configuration which is quite similar to the configuration which we've just seen.

The only difference is that instead of using the category sculpin_pagination, use pagination, as in the following example. Then, in it, set max_per_page as we did previously.

pagination:
    max_per_page: 3

Again, after saving the configuration and running either the generate or publish script, that content type will render a new maximum number of records. All other content types will be unaffected.

And That’s a Wrap

If you’re thinking of migrating away from your current blog or website backend to a static site generator and you want to know anything more about Sculpin, then check out its documentation. If you are already using Sculpin and have any tips or suggestions to share, please do so in the comments.

Tagged with: writing / getsculpin / static site generators

Join the Email List

If you enjoyed this post, why not join the email list and get all future posts straight to your inbox? In addition, you'll get background information, extra research, and other content that's only available on the list. I promise I'll NEVER spam you. And you can unsubscribe at any time.