Trouble with List Templates and Nested Branch Bundles

Hi lovely peoples:

I am somewhat new to this forum, but I have been using Hugo for quite some time. In the past I have been able to find solutions to my problems, but alas, I am stuck on something. Please bare with me as I get accustomed to posting on this forum. As I get more involved with Hugo, I plan to share some of the tips I learned along the way.

I am creating a documentation site (https://github.com/jkinley/jk-docs/). It has the general structure like this:

Docs > Gizmos > Overview(_index.md)
Docs > Gizmos > Tutorial.md
Docs > Gizmos > Articles > _index.md /* Branch Buddle and Subsection */
Docs > Gizmos > Articles > Article 1.md
Docs > Gizmos > Articles > Article 2.md
Docs > Gizmos > Articles > Article 3.md
Docs > Gizmos > Resources

On the Gizmos overview page, I need a List Template that will output the following:

  • Tutorial
  • Articles (link to articles _index.md)
  • Resources

If I {{ range .Pages }} I get the pages and if I {{ range .Sections }} I get sections. But I would like both in one list. Make sense?

Please let me know if you have any questions. I did my best to write this out clearly and succinctly. As always, I appreciate any help. Hopefully the demo repo I built helps this time.

Respectfully,

jkinley

I know next to nothing about this, but is this possibly related?

Thanks, Dixonge. I will take a closer look at ‘where’ and see what I can cook up. When I find the solution, I have a feeling its going to be so simple. And then I will feel silly.

Cheers : )

You could nest the two ranges if you are looking to list one within the other.

Thanks Rick,

Hmmmm. I thought I tried that. I’ll give it another go.

After thinking about this some more, I guess what surprises me is that I have not found a single theme that provides an example of this. I’d have thought that this would be a pretty typical use case.

Regards,

Jeff

If I’m understanding your question, here’s how I’d attempt it:

  • create a variable for each set of pages I want (you’ll use where and Section here)
  • use the union function to add all the pages together, and store that in a another variable
  • range over that variable

Hey Zack, thanks for the input. I seemed to have solved this issue just about 15 minutes ago. Lol!

I did not use the first step you suggested. I guess I could see using “where” and “section” if you were trying to find pages in a particular section. But in this particular case I just want a list template that shows any pages or the root page of any subsections.

In the end it was two lines of code. So surprised not to see something like this in one of the themes. Am I doing something wrong? Does this not seem to be a sensible way to organize a Docs site?

{{ $combined := union .Pages .Sections }}
{{ range $combined.ByWeight }}
  <li class="list list--bare card">
    <a href="{{ .RelPermalink }}"><h3>{{ .Title }}</h3></a>
    <p>{{ .Summary }}</p>
  </li>
{{ end }}

I added my changes to my repo. I hope this helps someone else.

Thanks again,

Jeff

Much more terse than I had in mind, which is good. I don’t think you’re doing anything wrong here – you’ve wrote template code that meets your needs.

Thanks, buddy. Appreciate the help. I will let you know how the site progresses. I am sure there will be some other things that spring up.

Jeff

Back on my desktop, here’s an example. You could add this to your /layouts/docs/list.html:

{{ range .Sections }}
<b>{{ .Name }}</b><br>
  {{ range .Pages }}
    {{ .Name }}<br>
  {{ end }}
{{ end }}

It’s homed under your top level docs section, so it finds the sections under that. The names it’s grabbing are from the frontmatter in your /docs/[gizmos|widgets]/_index.md files.

Looking at your repo you don’t have pages in your Widgets section yet, so the above template will result in:

Gizmos: Overview
Gizmos: Tutorial
Gizmos: Resources
Widgets

Hi Rick, I did try your method again and I got it working. However, I only want the link to the top-level page for the sub-section and not the children. So the list template should display:

  • Tutorial
  • Articles
  • Resources

And not:

  • Tutorials
  • Articles
    • Article 1
    • Article 2
  • Resources

Hope this makes sense. But glad to explore this fully because I can see where your method will come in handy too.

Be well,

Jeff

1 Like