Pagination implementation (FEEDBACK APPRECIATED)

I have waited for someone else to pick up this ball, but got tired of waiting …

I have a working implementation, but it needs some polishing before I open a Pull Request.

Strange enough, the hardest part of this was to come up with some good terms for the “pagination stuff” – so feedback appreciated.

You can see it in action on my site. It works for taxonomies and sections.

A taxonomy (more by navigating the menu):

A section:

The pages are built on the form:

[SECTION/TAXONOMY]/page/1/index.html => redirect to  [SECTION/TAXONOMY]/index.html

The partial below shows how the pagination navigation is built:

I believe this should be pretty feature-complete, and most of the terms I’m pretty happy with.

But there is a Paginator with a Paginated slice … This sounds fishy. The top level Paginator sounds OK, I guess – and the Paginated should be Pages, but that’s in use for something else.

Note: I will make sure that you would have to turn this feature on, and if you do nothing it will work as before.



Here’s the (In progress) Pull Request:

It’s very unpolished.

While we’re still in pre-1.0, my vote is to turn on pagination by default. That’s what anyone migrating to Hugo is going to expect.

I also think you should add the pagination ul from above as a built in partial / shortcode. That makes a good default for most people, and people can copy it out if they want to customize it.

I also think the built-in redirect for /page/1 is a great touch.

I just glanced through the code in your PR, and I don’t see why you couldn’t have a {{ .Paginator.Pages }}. I think the top level Paginator is good, but I would definitely rename .Paginated to .Pages.

I’ve tested the feature in your site and it works.
Thank you

Thanks for the feedback.

I actuallly have .Pages – which is what you would expect in Hugo, all the pages for “that page”, and what you would use to actually iterate and show post/page info in the list template:

{{ range .Data.Paginator.Pages }}

And then there is the Paginated list, holding pagination info (next, prev, page count etc.), used to build the paginator buttons:

{{ range .Data.Paginator.Paginated }}

I guess it boils down to having a different term for the last one.

On an added note there still is

{{ range .Data.Pages }}

Available, which is all pages for “all pages”…

Thinking about it, I think the correct term for what is now Paginated should just be Pagers.

What about .Paginator.Info, .Paginator.Details, .Paginator.Options or .Paginator.Config?


I see Jekyll also uses the terms Paginator and Pager – I’ll stick with that.

Hi there,

Thanks @bjornerik for the time spent on this feature :slight_smile:

I wanted to give it a try in order to help you with some feedback but unfortunately I haven’t succeeded to make it works.

Here are the steps I have done:
On Hugo’s side

  • I have downloaded the last version of the Git repo and applied your PR (I can see you changes applied)
  • I compiled Hugo regarding the documentation and everything works like before

On my website

  • I’ve created a new website and added few contents
  • I have defined the number of post on each page in the site’s configuration file
  • I have created a pagination.html template and included it in the list.html file

Did I miss something ?

I’ve posted on github the source of my website in case :

Thanks for taking the time to test this.

I tried to clone and fire up your test repo, but don’t see any layout files (you mention the list.html file, but it’s not in the repo)

Looking at the steps you’ve taken, my guess this is the info you need:

{{ range .Data.Paginator.Pages }}

Contains the pages for “the current page”.

{{ range .Data.Pages }}

Contains ALL pages (like today).

So you would have to edit the list.html to reflect this.

I’m on the fence about how “clever this is”.

Oops, seems something wrong happened. You should now see the theme

Replacing {{ range .Data.Pages }} by {{ range .Data.Paginator.Pages }} gave me a white page of results

Well, it’s the famous “it works for me”. When I fix the list.html according to the above, I get working pagination (it looks ugly, but it works).

I suspect you run with wrong Hugo version (or the patch went wrong). But there is some fishy about your category setup, will check.

EDIT IN: Seems like you found an issue with taxonomies and themes (or something). Weird. Thanks for the testing! Will fix.

@juliendubreuil I have committed a fix for my (stupid) issue that wouldn’t let pagination work on taxonomies on your test sample.

Again, thanks for the testing.

Well, I pulled the master branch of Hugo, which one should I have used ?

My feature branch:

It’s still in pull request modus.

Hi @bjornerik

Sorry for the delay I only found the time now to test. I’ve downloaded your branch, compiled Hugo, changed the variable name to loop over as you mentioned in a comment above in my theme and built my website but I still have nothing (whether on the homepage or categories pages).

Did you changed something else on my testing example to make it works ?

I will add a pull request later to your branch with my changes - but I’m pretty confident that if works fine. I have it runnng full throttle on 4 sites now, 2 of them use a theme.