Template lookup order

I struggle a lot with the template lookup order: it just feels awkward to me.
After reading the docs I can see a lot of complexity in the way a simple layout is chosen: section, type, language, theme, layout param… Sheeeez !!
It’s made for a lot of flexibility I can imagine, however I stumble on empty or 404 pages quite a lot because I was not able to align planets together… I am surely too dumb to grasp the initial concept here, but I thought I’d throw some ideas to just make things a bit more “natural”.

The /layouts folder

This folder (the one at the root of Hugo sites, not the one in themes) seems irrelevant to me as it literally OVERRIDES any theme… Really don’t know in which situations one should use it and it feels to me that this folder exactly works upside down.

Solution: the /layouts folder should never override themes !!! If user EXPLICITLY takes the time to open config.html to write that he wants to use theme XYZ… why override that EXPLICIT assertion ? Instead it should be used as a fallback theme’s folder if Hugo fails to find relevant template in a given theme. I would even argue that this folder should be shipped with some ugly blank single.html + list.html + taxonomy.html + index.html templates by default to overcome the frustration to find 404 pages when no theme is provided…

The theme config

It’s cool to define a theme, but sometimes (most of the time ??) we can’t rely on one and only one theme for a whole site. In fact, it seems to me that it should be like that in heaven, but in the real world: one might need a template from theme ABC within the baseof from theme XYZ while having a special handy shortcode of theme “whatever”. Today, one should overthink play with some type + section + layout to more or less get some “flexibility”. In case of shortcodes, one should literally copy-paste cool shortcodes to all his themes or make them available on the /layouts folder (which I should remind: OVERRIDES THEMES…)

Solution 1: the layout param should accept something like theme/template
Solution 2: a theme param should be available to intelligibly infer theme + template without going to the docs to check Hugo’s lookup order. While a “defaultTheme” config should just do what it sounds like…

The layout param

This param can lead to a lot of confusion because it lacks of defaults (check point #1). If one defines layout = "myTemplate", Hugo will correctly look for a template with that same name. However, for whatever reason I can’t understand, if this template is not to be found… we don’t build anything (serving 404) ? Why ?! Why not just fallback to single or list ?!

Solution: check solution of The /layouts folder to provide fallbacks.

I’d be happy to discuss these points. Also, if solutions already exists, I’d be happy to hear them: couldn’t find in the docs. :slight_smile:

Perhaps this helps: