How to Add Pagination to your Hugo Site?

Pagination is a handful option to show multiple items on a page. Hugo supports pagination for your homepage, section pages, and taxonomies. Adding pagination on Hugo site is pretty easy. There are two ways to add this. One is the default Hugo Pagination Template and another is a custom made pagination template.

Adding Default Hugo Pagination

To add an internal pagination template is very easy. Just include the default template on the page we want to add pagination. The default template code is:

{{ template "_internal/pagination.html" . }}

By default, this will show 10 items or pages for each pagination number. We can also override it very easily. Just go to config.toml file and add a paginate parameter and give it a value. For example, the parameter value is given below.

paginate = 6 

Now, 6 items will be shown for each pagination number instead 10 items.

Adding Custom Pagination

To add a custom pagination template, we have to create a pagination.html file. To do this,

1.  Go to the theme folder. 
2. Go to the Layouts folder.
3. Find the Partials folder and enter it.
4. Create a pagination.html file
5. Copy and paste the following codes 
   

{{ $paginator := $.Paginator }}
<!-- Number of links either side of the current page. -->
{{ $adjacent_links := 2 }}
<!-- $max_links = ($adjacent_links * 2) + 1 -->
{{ $max_links := (add (mul $adjacent_links 2) 1) }}
<!-- $lower_limit = $adjacent_links + 1 -->
{{ $lower_limit := (add $adjacent_links 1) }}
<!-- $upper_limit = $paginator.TotalPages - $adjacent_links -->
{{ $upper_limit := (sub $paginator.TotalPages $adjacent_links) }}
 
{{ if gt $paginator.TotalPages 1 }}
<nav aria-label="Page navigation" class="w-100">
  <ul class="pagination justify-content-center pagination-lg">
    <!-- First page. -->
    {{ if ne $paginator.PageNumber 1 }}
      <li class="page-item">
        <a class="page-link" href="{{ $paginator.First.URL }}">
      First
        </a>
      </li>
    {{ end }}
    <!-- Previous page. -->
    {{ if $paginator.HasPrev }}
      <li class="page-item">
        <a class="page-link" href="{{ $paginator.Prev.URL }}" rel="next">
          ←
        </a>
      </li>
    {{ end }}
    <!-- Page numbers. -->
    {{ range $paginator.Pagers }}
      {{ $.Scratch.Set "page_number_flag" false }}
      <!-- Advanced page numbers. -->
      {{ if gt $paginator.TotalPages $max_links }}
        <!-- Lower limit pages. -->
        <!-- If the user is on a page which is in the lower limit.  -->
        {{ if le $paginator.PageNumber $lower_limit }}
          <!-- If the current loop page is less than max_links. -->
          {{ if le .PageNumber $max_links }}
            {{ $.Scratch.Set "page_number_flag" true }}
          {{ end }}
        <!-- Upper limit pages. -->
        <!-- If the user is on a page which is in the upper limit. -->
        {{ else if ge $paginator.PageNumber $upper_limit }}
          <!-- If the current loop page is greater than total pages minus $max_links -->
          {{ if gt .PageNumber (sub $paginator.TotalPages $max_links) }}
            {{ $.Scratch.Set "page_number_flag" true }}
          {{ end }}
        <!-- Middle pages. -->
        {{ else }}
          {{ if and ( ge .PageNumber (sub $paginator.PageNumber $adjacent_links) ) ( le .PageNumber (add $paginator.PageNumber $adjacent_links) ) }}
            {{ $.Scratch.Set "page_number_flag" true }}
          {{ end }}
        {{ end }}
      <!-- Simple page numbers. -->
      {{ else }}
        {{ $.Scratch.Set "page_number_flag" true }}
      {{ end }}
      <!-- Output page numbers. -->
      {{ if eq ($.Scratch.Get "page_number_flag") true }}
        <li class="page-item{{ if eq . $paginator }} active{{ end }}">
          <a class="page-link" href="{{ .URL }}" >
            {{ .PageNumber }}
          </a>
        </li>
      {{ end }}
    {{ end }}
   <!-- Next page. -->
    {{ if $paginator.HasNext }}
    <li class="page-item">
      <a class="page-link" href="{{ $paginator.Next.URL }}" >
        →
      </a>
    </li>
    {{ end }}
    <!-- Last page. -->
    {{ if ne $paginator.PageNumber $paginator.TotalPages }}
    <li class="page-item">
      <a class="page-link" href="{{ $paginator.Last.URL }}">
  Last
      </a>
    </li>
    {{ end }}
  </ul>
  <!-- </nav> -->
</nav>
{{ end }}

6. Save it

Now go to the list page where pagination will be added. Suppose we want to add pagination on the blog page. Then go to the <HUGO ROOT>/themes/yourtheme/layouts/blog/list.html. First, embed codes that we want to show for pagination inside “{{ range .Paginator.Pages }}... {{end}} ”. If  we want to show only the title, then the code will be looked like the following codes:

{{ range .Paginator.Pages }}
     {{ .Title }}
{{end}}

and finally, now add the following code at the end or where pagination will be added.

{{partial "pagination.html" .}}  

Wrap-Up Discussion

Pagination is a very integral feature of any website. It allows users to easily move to the page that they want to view. We can use this on various posts, articles, blogs, etc. In Hugo, creating a pagination page is super easy. Furthermore, we can easily use it on various pages by simply calling them {{partial "pagination.html" .}} on that page. That’s all about adding pagination on the Hugo websites.