It’s clear that template lookup order is something people struggle with (1, 2, etc.) — me included!
I think there’s two main problems:
The docs are unclear; they provide examples but there’s no way to really figure out what Hugo considers a list or a “page” or a “type” or a “section” without deeply examining the docs
There’s no way to debug exactly which templates are being used without inserting debug statements into every template
I’m not sure how to fix the docs — I don’t understand template lookup order well enough to rewrite them — but a tool I’d find massively helpful is a Hugo subcommand to determine what the exact template lookup order is. I’d imagine it being used as something like hugo lookup content/section/xxx.md or hugo render content/section/xxx.md, and it would print out the templates being looked up (and if they’re found or not) as well as what templates are looked up when rendering that template. Finally, such a tool might output the fully rendered output.
Would there be support for making such a command? My schedule’s a bit tight at the moment, but I might be able to put together a pull request in a few weeks.
It’s a good idea, but it’s hard to execute. “hugo lookup content/section/xxx.md” would be contextual and that is not enough information to give one answer. What we really need (I think there is a GitHub issue about this) is some kind of structured event log which can be turned on, where you see exactly what is happening with a page from end-to-end.
The examples in the docs are actually auto-generated. So they are correct.
I think you really need to understand a few of the basic concepts to really enjoy Hugo: list pages, regular pages, type and section and layout should get you far.
So in my debug theme, I print those in top-left of each page… sample site. Then navigate different pages like homepage, /tags, /posts, etc to see how they change.
What other information is needed to determine lookup order, other than config.toml?
I’m sure they’re correct, but if you’re looking to figure out what template is actually being used in some page there’s not really enough information in the table to figure out where you should be looking. I just think that the docs aren’t extensive and complete enough.
I’d argue that everything past “regular pages” isn’t a basic concept. I’m speaking for myself here, but I’d imagine others have the same experience; when I started working with Hugo, I was looking for a templating engine so that I could make changes to the header / footer of my pages without touching every .html file — for me, at least, all of Hugo’s other features are bonuses. I think beginners should be able to start writing templates and regular pages (i.e. top-level .md files in content/) and navigate from there into features that extend past “template engine” when they need to (archetypes, taxonomies, RSS feeds, list pages).
I guess I have the advantage of arriving at Hugo via a number of other generators. So actually, I’ve found much of Hugo’s layout to be more obvious than, lets say Jekyll or Hexo.
But you are certainly correct in saying that, for beginners, the many possible layouts and the differences between them are certainly confusing. It is particularly challanging to try and understand why the page that shows the list of categories for example is of Kind taxonomyTerm when, logically, you would expect that to be of Kind taxonomy.
Then the difference between the singular and plural forms is also confusing. Though Hugo is not the only tool that differentiates this way.
Of course, for a Hugo beginner, one of the least consistent and most confusing thing is the seemingly random selection of casing for variable names.
It is certainly interesting to see that @kaushalmodi has done what I suspect most of us have to do and that is to build a test site with lots of debugging. For myself, I’ve had to build a load of partials and shortcodes to find out what is happening and I too have started to build a set of notes about how Hugo puts things together. If you look at my testing site (where you will see that I am trying to migrate from my live blog at it.knightnet.org.uk) https://confident-carson-5eac42.netlify.com, you will see some debug information in the sidebar.
There isn’t a 1:1 mapping, that is my main point. We could add a command, but that would be too much work for little.
We all have different needs in this department.
I have no problems with the template lookup order (most of the times knowing about _default, the /sectiona and single.html and list.html is all I need), but a event logger would be useful in other cases.
Yes, I certainly agree that an event logger would be useful. A subcommand would be nice but obviously isn’t critical. Is #4481 the issue you were talking about? If you can narrow down what format you’d like the log to have I’d be happy to help contribute.