How to Configure Pagination in Sculpin

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.

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?

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