Introduction
Pagination is a way of dividing large amounts of content into smaller, more manageable pages. This can make it easier for users to find the information they’re looking for and it can also improve the overall performance of your site.
In this blog post, I will show you how to add pagination to your Hugo site. I will cover two methods: using the built-in template and creating a custom template. The version of Hugo I use here is 0.115.1.
Add pagination using the built-in template
The easiest way to add pagination to your Hugo site is to use the built-in template. To do this, you need to include the following code in your template:
{{ template "_internal/pagination.html" . }}
This will load the built-in pagination template and display it on your page.
A very important configuration for me is paginate which can be configured in the hugo.toml file. This property defines how many entries should be shown on one page. The default setting is 10 but I like to show only 6 per page as it looks better in my eyes. Here you can see the configuration:
paginate = 6
In the last step I build a simple layout to display each page. Therefore I used the .Paginator which helps to build a pager menu. This feature is currently only supported on homepage and list pages (i.e., taxonomies and section lists).
The simplest way is just to call .Paginator.Pages from a template. It will contain the pages for that page.
I went with another solution: .Paginate.
{{ range (.Paginate .RegularPagesRecursive).Pages }}
With this I can iterate over the pages and create a layout.
Here is a full example for the list.html.
{{ range (.Paginate .RegularPagesRecursive).Pages }}
<div class="content description mb-1">{{ .Summary }}</div>
{{ end }} {{ template "_internal/pagination.html" . }}
First each page will display the summary and at the end of the page the pagination template will be shown. For a full documentation look at pagination documentation.
Add pagination using a custom template
If you want more control over the look and feel of your pagination, you can create your own custom template. To do this, you need to create a new template file in your site’s templates directory. The name of the template file should be pagination.html. In this file, you can add your own HTML and CSS code to customize the look and feel of your pagination.
If you want to build custom navigation, you can do so using the .Paginator object, which includes different properties which should be handled e.g. PageNumber, URL and many more. For a full list look at the pagination documentation.
Conclusion
In this blog post, I have shown you how to add pagination to your Hugo site. I have covered two methods: using the built-in template and creating a custom template.
I hope this blog post has been helpful. If you have any questions, please feel free to leave a comment below.