Adding Pagination

Once you have more than a handful of posts, your archives pages are going to get very long. And your main blog list page will grow and grow until it’s too big to be useful. To handle this, you can break up the list of results into multiple pages, with links to navigate between the list pages. This process is known as pagination.

Hugo has built-in pagination support, and it’s enabled by default. All you have to do is change how you fetch pages and add pagination navigation to your layouts.

To use pagination, use .Paginator.Pages instead of .Pages in your range statement, like this:

Hugo defaults to showing 10 pages at a time with its paginator, but you can override this in the layout. Let’s explore this by applying pagination to the list layout for posts.

First, create another post in your site so you have more than two pages. Use hugo new to create the page:

Then, open themes/basic/layouts/posts/list.html and modify it to use the paginator and the built-in pagination template. For now, set the number of pages to show to 1 since you only have three pages and you’ll want to be able to test out the navigation:

Save the file. When you view the site, the pagination won’t look very pretty as shown in the screenshot.

Hugo’s internal pagination template uses markup compatible with Bootstrap,^[25] the popular CSS framework. Since you’re not using Bootstrap in this theme, you’ll have to whip up a few styles. If you view the source of your page in the browser, you’ll see markup like this for the pagination:

Hugo’s pagination template generated a list of links with various classes that you can use to style the elements. There are classes to identify the active elements, disabled elements, and regular elements.

To style this quickly, use a method similar to how you styled the navbar and use Flexbox. Open the themes/basic/static/css/style.css file in your editor and add the following code to style the pagination container:

On larger screens, you constrain the width to be 30% of the page. The margin: 0 auto line centers the element horizontally.

Next, add this code to define how each pagination button looks by giving it a border and some width:

Then style the individual links. Set each link to display: block so it fills the parent container. This makes the links easier to click, as the click target is the entire box, rather than the text:

Finally, add code to change the colors for the active page link and the disabled links:

View the posts page, and this time you’ll see styled pagination:

Now that you know the pagination works, open themes/basic/layouts/posts/list.html and change the number of paginated results to 10 posts:

Alternatively, since the default is 10, change the range line back to the original code:

You can then control the number of results globally in the site’s configuration by adding the Paginate field to config.toml:

With pagination in place, your blog list pages will be more manageable for your visitors. Now let’s add interactivity to your blog posts with comments.