Confusing template resolution for lists

More feedback than anything but I found it really confusing that you can have ./content/doc/*, and will source ./layouts/doc/single.html, but the index or “list” page /doc/ sources ./layouts/section/doc.html not ./layouts/doc/list.html to parallel the _default list.html.

I’m still new to Hugo so maybe I just haven’t grokked that stuff yet, but some of that stuff feels unintuitive and as a noob, it would be really helpful to have some logging that shows what is being attempted. Tiny nitpick: “baseof” reads weird to me too compared to just “base”.

Aside from that and it being a little confusing to set up “regular” landing pages it has been great! I think that’s mostly a doc issue, it seems easy once you just override the url manually. Big thanks for the work done it.

@tjholowaychuk I am hoping to improve the docs and appreciate this feedback. The “lookup order” and some of the naming conventions can be a bit confusing at first.

I would really appreciate any and all criticism you can send in my direction in terms of pain points for “newbs” (in inverted commas for more than one reason).

Seriously. Be verbose.


Will do! Thanks for being receptive to it.

Another that I just hit is that having ./content/doc/PRODUCT/*.md would maybe ideally resolve to doc layout(s) unless there happens to be one for that given sub-section. I seem to be getting a blank page there by default, logging would be super helpful.

Without knowing the other Hugo capabilities it’s hard to say if my expectations for template resolution collide or ruin other features haha, but I’ll try and come up with a list of stuff that I’ve been assuming. Maybe I should be using taxonomies for this instead.

So far:

  • pretty sure “baseof” isn’t a word, which made me think it was an ad-hoc filename vs a special-cased one
  • expected ./content/doc to use ./layouts/doc/list.html instead of ./layouts/section/doc.html
  • expected ./content/doc/PRODUCT/*.md to inherit the doc list template (getting blank page, can’t get anything to render, no errors)
  • marketing pages were confusing until I grokked that ./content/page with separate “layout” and explicit “url” is totally fine
  • displays a nested post, however its “list” appears to not work, nesting seems fine otherwise
  • defining an index page that supports partials etc is weird, using _default/list.html leads to duplicate content with taxonomy listing etc so that’s not a good solution

This in particular is really confusing to me.

All I want is docs listed per product, /doc/ renders /section/doc.html with the title/description of ./content/doc/ping/ not ./content/doc/, and /doc/ping/ simply outputs a blank page. I can’t get it to anything else regardless of specifying type & layout.

<img src="//" width=“168” height=“500”

This seems like the exact kind of thing Hugo is made for, but it’s tough to get going, seems like it really falls apart when you try and nest things, or I’m doing it the complete wrong way.

EDIT: it seems like taxonomies might be ok, I didn’t grasp that directories nested in ./content/TYPE are effectively just for namespacing and nothing else, that’s starting to make sense now. I was expecting the nested there to have access to the files in that dir.

If you want to change your content source organization around a bit, you could always set permalinks in your config… i.e., move the ping folder up a level and prepend doc accordingly. That said, if you check the section for both doc pages and ping pages, you’ll notice they both return doc. (This is just me expanding a bit on the above GH enhancement).