Direction matters when looking up the template order in Hugo, conceptually

templates
gohugo
Tags: #<Tag:0x00007f0fa409ecb8> #<Tag:0x00007f0fa409eb78>

#1

In Hugo we have something called the template lookup order:

We get a bunch of questions about this in the forums all the time, when someone is trying to make a very specific page do a very specific thing. Ultimately our process is to figure out what the name of the file should be, and move the user along their way. That is very unsatisfactory, because I want to “teach them to fish”, but I can’t quite explain it.

I never ran into this with WordPress theme makers, but then again I don’t hang out where they do. That is to say, in WP theming is a distinct sub-domain of the project ecosystem. For Hugo, theming is 80% - 99% of a project. Consider just the use of a shortcode in a blog post; we’re all themers now! And I try to tell people that about Hugo, but for other reasons, such as licensing (it just templates) or security (it’s just templates) or hosting (it’s just the output from templates). Anyhow, side point, but background on where I’m coming from.

So, what is the “direction” I mention? When the system looks up which template should render a piece of content, it processes a list until it hits one that matches, and then stops.

Here’s the lookup order for a single page in the section called posts:

layouts/posts/single.html.html 
layouts/posts/single.html 
layouts/_default/single.html.html 
layouts/_default/single.html

If you set a layout in the front matter for that same piece of content, the lookup instead looks like:

layouts/posts/demolayout.html.html 
layouts/posts/single.html.html 
layouts/posts/demolayout.html 
layouts/posts/single.html 
layouts/_default/demolayout.html.html 
layouts/_default/single.html.html 
layouts/_default/demolayout.html l
ayouts/_default/single.html

And finally, to demonstrate how bonkers a lookup can be, here is a section for “posts” with a layout set:

layouts/posts/demolayout.html.html
layouts/posts/posts.html.html
layouts/posts/section.html.html
layouts/posts/list.html.html
layouts/posts/demolayout.html
layouts/posts/posts.html
layouts/posts/section.html
layouts/posts/list.html
layouts/section/demolayout.html.html
layouts/section/posts.html.html
layouts/section/section.html.html
layouts/section/list.html.html
layouts/section/demolayout.html
layouts/section/posts.html
layouts/section/section.html
layouts/section/list.html
layouts/_default/demolayout.html.html
layouts/_default/posts.html.html
layouts/_default/section.html.html
layouts/_default/list.html.html
layouts/_default/demolayout.html
layouts/_default/posts.html
layouts/_default/section.html
layouts/_default/list.html

When we talk about the “lookup order” and present these lists, we are pointing out the shape of how it works, whereas most people are just asking for the name of the file that creates the output they want. But looking up a template from the beginning of the lists as presented isn’t useful, in that “slow web” kind of way.

I start at the bottom, in layouts/_default. I make changes to templates as close to root as possible. If I need a single section to render differently, I don’t reach for a layout, I see if I can make simple changes to the layouts/_default/section.html. Fortunately, so much layout is done in CSS, so you can actually get away with a lot of conditional classes in strategic places on a document and get drastic changes. But if I need to output different HTML sections, I just step as many steps away from _default as I need to accomplish that.

Point?

I’m posting this here to let it digest for a bit. I’m not sure if if will ever be useful for folks just looking for a quick website, though on the other hand, if someone is looking for a simple or quick site, they shouldn’t need any more than the basic templates for list.html and single.html. So if we can explain this, um, method, maybe it will be useful. :slight_smile: