How to Configure Pagination in Sculpin

How to Configure Pagination in Sculpin

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


You might also be interested in...


Want more tutorials like this?

If so, enter your email address in the field below and click subscribe.

You can unsubscribe at any time by clicking the link in the footer of the emails you'll receive. Here's my privacy policy, if you'd like to know more. I use Mailchimp to send emails. You can learn more about their privacy practices here.


Join the discussion

comments powered by Disqus