←    Back

Category Pagination in Jekyll

This site was built on Jekyll – a blog aware static site generator. When I was building this, I wanted to separate my blog from my portfolio. Of course I would be using custom post type for my portfolio if I was developing on WordPress. Here I thought to stay straight and simple and I just created two site categories: portfolio and blog and I am using custom permalink which makes it difficult to use the default pagination setup. And I also want to paginate only the blog category.

Here, in this tutorial, we will discuss on how to paginate a specific category in Jekyll with custom plugin built from scratch.

Let’s get started.

Site Structure

In order for the plugin to work, I have removed the index.html from blog category (i.e. directory). Now my site structure looks like this:

I want the index.html in the blog category to be generated by the plugin. Here is the site structure I wish to have:

As you can see, index.html in the blog category will be generated by the plugin as the very first page of the pagination. And from second page onward, it will live in respective directories under pages directory.

Liquid Template

The template for iterating over the current set of posts and showing them look like this:

There should also be navigation links for previous and next pages. Here goes the template for that:

I include these templates in a heredoc inside my plugin.

The Configuration

Before diving into writing the plugin, we need to set some config options in the _config.yml file to make the plugin a bit more maintainable.

We need to provide an option to later modify number of posts in a page without touching the plugin. For this reason, we are going to include posts_per_page in our _config.yml.

The setting paginated_category will tell the plugin which category to use for pagination. We may hardcode this in our plugin, but it is a bit more professional to provide an option to change the setting later without looking at the plugin.

The Code

First, create a file CategoryPostPaginator.rb inside your _plugins directory.

The first class to create is the “Generator.” All generators are called by Jekyll at site build, so if you want code that’s going to create new pages or content, you want to sub-class this class.

When Jekyll calls a generator, it calls the generate method, so that’s the first method to implement. In our class, it loops through all the posts in the site and group the posts according to their position (or index). Then it crates a page for each group.

Next, we need to subclass the Page class for our specific needs. This code is very specific to my site, you may want to change the logic here to meet your needs. Basically, I am creating a series of pages to show category indexes. This code customizes the layout that’s used and adds some information to the generated page. I have included my liquid template in heredoc statement.

That is the end of our discussion. Hope you enjoyed it. Just give it a try.

The Author

Other Articles

  • How to use Zaq: Codeigniter Template Parser Engine

    Zaq is a PHP based template parser engine developed to work with Codeigniter. This library has been developed for developers to integrate php codes in views easily. Using this library will also allow the view file to be more readable. View files in Codeigniter (or in any other framework following MVC) always contains both html and php codes which make them a bit harder to read. This problem can be eradicated by using a parser engine which makes the view files a lot more easier to work with.

  • 15 Best Bootstrap Alternatives for Web Developers

    Choosing the right framework that is the perfect fit for your projects could be a little bit overwhelming – there are a lot to choose from. Perhaps, you want to go with popular choices like Bootstrap or Foundation, but if your website is going to be a fairly simple one, you won’t be needing most of the building blocks and materials included in the default package. The good news is that there are a handful of alternatives that are much leaner than Bootstrap or Foundation. Most of these frameworks ship with just the right amount of styles and components to help you get started, while allowing you to be able to extend them in the direction you want for your project.

  • 8 Icon Fonts to speed up Website Design Process

    Icon Fonts are nothing but fonts. But, instead of containing letters or numbers, they contain symbols and shapes. You can style them with CSS in the same way you style regular text. They’re ideal for small, frequently used shapes such as email, envelopes, telephones, widget controls and social media logos. Here is a list of most popular and easy-to-use icon font sets.

  • Download ZIP File Dynamically with PHP

    Here we will see how we can make a webpage act as an initializer to download a zip file. We will just provide the location of the file and PHP will download it to the user. In the back-end, the HTTP headers are responsible for the download. We will set the headers with PHP.

  • How to Add Scalable Vector Graphics (SVG) to Web Page

    Scalable Vector Graphics (SVG) is an XML-based vector image format for two-dimensional graphics with support for interactivity and animation. If you want to embed your hand-crafted SVG in your web page, you can use any of the methods discussed here.

  • Create File Upload Class in PHP

    The basic process of providing a HTML form for uploading user submitted files to the server with PHP is fairly easy and simple. But there are some security implications that many of us are unaware of. We will be building a custom PHP class for secure file upload. This class will check the type and size of the file and rename the file in case of duplication.