Why does the paginator go into child sections?

(Full example here: https://gitlab.com/j12t/hugo-test )

I have the following content structure:


and I’m working on a list.html that will show the summary of the pages “the next level down” but not the level below that. In other words:

  • at / (root of the site), I want to see testing-a and testing-b (and not testing-a-a)
  • at /testing-a/ I want to see testing-a-a

but my code currently “flattens” testing-a-a and testing-b into the same list, so I see both at /, and not testing-a, like this:

    a-a summary
    b summary

The relevant code in list.html:

{{   $p := .Paginator }}
{{   if $p.Pages }}
   <div class="children">
{{     partial "range-dl-summary" ( $p.Pages.ByTitle ) }}
{{   else }}
{{     block "no-posts" . }}
   <p>No content so far.</p>
{{     end }}
{{   end }}

(This structure is to enable me to reuse range-dl-summary in different contexts)


  1. It appears .Paginator.Pages returns all regular pages recursively down (not sections). Why does it do that? I thought it would stop at section boundaries?
  2. how do I make it stop going into the child section, and return the child section’s _index.md instead, without having to change my structure significantly?

If you try it out from git at https://gitlab.com/j12t/hugo-test , note there is a child theme that’s a git submodule and you need to check that out, too.

It explains it at https://gohugo.io/templates/pagination/#list-paginator-pages

There are two ways to configure and use a .Paginator :

  1. The simplest way is just to call .Paginator.Pages from a template. It will contain the pages for that page .
  2. Select a subset of the pages with the available template functions and ordering options, and pass the slice to .Paginate , e.g. {{ range (.Paginate ( first 50 .Pages.ByTitle )).Pages }} .

Select the subset of pages you want, possibly with .FirstSection. :slight_smile:

This is very confusing – this “API” needs some work.

But thank you, I got something to work.

I think what’s confusing is your use of multi-level post type directories. The second level _index.md might be better an index.md. But without a test repo I wouldn’t know. I have quite some paginator use cases, but none where it goes into multilevels with _index.md.

Have a look at this thread here, the docs they talk about might give some hints - I remember though reading it in the final docs already too:

Which part is confusing and needs work?

@maiki the documentation

Please be more forthcoming in your commentary or refrain from discussing it here. We need you to do more when you contribute here. :slight_smile:

1 Like


Sure, let’s take https://gohugo.io/templates/pagination/#additional-information for an example. I am quoting it here in its entirety:

Additional information

The pages are built on the following form ( BLANK means no value):

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

Now let’s dissect it a bit:

The pages

Reference, but the referent is missing, not mentioned in this section. Which pages would these be? No idea.

are built

Built by whom? How? Where are they now, these built pages?

on the following form

What follows appears to be a list, not a form, but maybe it’s a template followed by examples of usage? Can’t really tell from context. Perhaps the writer meant “following the template below”? Or perhaps not?

and then we are shown the so-called form:

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

Are we supposed to read that first line as [SECTION/TAXONOMY/]/index.html since we know that BLANK means no value?

I think => redirect to [SECTION/TAXONOMY/BLANK] is actually a comment, because it doesn’t make sense as an arrow function, but does this comment mean that [SECTION/TAXONOMY/]/index.html redirects to [SECTION/TAXONOMY/BLANK]? Who knows?

In short: This section talks about the way the index pages are built. It lists how the pagination links are named and explain, that page/1/index.html is redirected to the index page above because their content is basically the same.

Hugo is the one building the pages.

Much of the documentation is based on discussions here on the forum. You could give back to the community by rewriting them so that people with no previous knowledge of Hugo can understand them.

The “arrow function” quip was funny though.


You could give back to the community by rewriting them

I could give back, maybe, if I had the wealth of contextual knowledge that comes with lurking the forum for years, but I do not have that since I have only been here for less than a year.

people with no previous knowledge of Hugo can understand them

Thanks for so neatly summarizing my wordy post! indeed, documentation should be immediately useful for people with no previous knowledge, and right now it isn’t.

Hugo is the one building the pages.

Does it also build these links?

explain, that page/1/index.html is redirected to the index page above because their content is basically the same

Can I ask what BLANK does/is, though? Or indeed, what [SECTION/TAXONOMY/BLANK] is supposed to stand in for?

Look. I have to lurk the forum now so I won’t have time for an answer. The OP’s question is solved. I’ll flag this post so it can be closed.

This topic was automatically closed 2 days after the last reply. New replies are no longer allowed.