# Template lookup order

**URL:** <https://discourse.gohugo.io/t/template-lookup-order/10619>\
**Category:** feature\
**Created:** [February 18, 2018, 9:39pm UTC](https://discourse.gohugo.io/t/template-lookup-order/10619 "2018-02-18T21:39:11Z")\
**Posts on this page:** 2\
**Page:** 1

<div class="post-metadata">

**Author:** ![Jonarod](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/jonarod/32/5075_2.png) [@Jonarod](https://discourse.gohugo.io/u/Jonarod)\
**Post date:** [February 18, 2018, 9:39pm UTC](https://discourse.gohugo.io/t/template-lookup-order/10619/1 "2018-02-18T21:39:11Z")

</div>

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. 🙂

---

<div class="post-metadata">

**Author:** ![Leo\_Merkel](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/leo_merkel/32/3321_2.png) [@Leo\_Merkel](https://discourse.gohugo.io/u/Leo_Merkel)\
**Post date:** [February 18, 2018, 9:59pm UTC](https://discourse.gohugo.io/t/template-lookup-order/10619/2 "2018-02-18T21:59:41Z")

</div>

Perhaps this helps:

> [@See which template is used by Hugo](https://discourse.gohugo.io/t/see-which-template-is-used-by-hugo/9983/2):
>
> Cool - Thx for sharing and your very good post! I prefer to see the chosen templates and partials as comments in the html. Include e.g. {{ \<!-- \_default/terms.html --\> | safeHTML }} or {{ `\<!-- partials/head.meta.html --\>` | safeHTML }} in the templates and partials. To keep track in the blocks: {{- block "main" . }} {{ `\<!-- block main _default/baseof.html --\>` | safeHTML }} {{- partial "main.blog.date.html" . -}} {{- partial "main.toc.single.html" . -}} {{ `\<!--…

> [@My experiences with Hugo's template lookup order](https://discourse.gohugo.io/t/my-experiences-with-hugos-template-lookup-order/9959/1):
>
> I just want to share some of my experiences by testing the lookup order for templates. I tested these and wrote them down the same time. Nevertheless I could be wrong in some cases. So if you have better solutions or remarks please don’t hesitate to share. In this example we work with a sample directory hugo-docs and different layout variants. For this purpose we create this directory (content/hugo-docs) and also create an index.md (note the spelling!) in this directory. This index.md will lat…