# Preview actual template lookup order

**URL:** <https://discourse.gohugo.io/t/preview-actual-template-lookup-order/11443>\
**Category:** feature\
**Created:** [April 8, 2018, 8:20pm UTC](https://discourse.gohugo.io/t/preview-actual-template-lookup-order/11443 "2018-04-08T20:20:57Z")\
**Posts on this page:** 8\
**Page:** 1

<div class="post-metadata">

**Author:** ![9999years](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/9999years/32/5671_2.png) [@9999years](https://discourse.gohugo.io/u/9999years)\
**Post date:** [April 8, 2018, 8:20pm UTC](https://discourse.gohugo.io/t/preview-actual-template-lookup-order/11443/1 "2018-04-08T20:20:57Z")

</div>

It’s clear that template lookup order is something people struggle with ([1](https://discourse.gohugo.io/t/template-lookup-order/10619), [2](https://discourse.gohugo.io/t/unify-the-section-template-lookup-order-please-comment/5648/2), etc.) — me included!

I think there’s two main problems:

1. 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
2. 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.

---

<div class="post-metadata">

**Author:** ![bep](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/bep/32/3332_2.png) [@bep](https://discourse.gohugo.io/u/bep)\
**Post date:** [April 8, 2018, 8:44pm UTC](https://discourse.gohugo.io/t/preview-actual-template-lookup-order/11443/2 "2018-04-08T20:44:53Z")

</div>

> [@9999years](#):
>
> 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

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.

---

<div class="post-metadata">

**Author:** ![kaushalmodi](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/kaushalmodi/32/2567_2.png) [@kaushalmodi](https://discourse.gohugo.io/u/kaushalmodi)\
**Post date:** [April 8, 2018, 8:51pm UTC](https://discourse.gohugo.io/t/preview-actual-template-lookup-order/11443/3 "2018-04-08T20:51:00Z")

</div>

> [@bep](#):
>
> 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.

+1

So in my debug theme, I print those in top-left of each page… [sample site](https://hugo-sandbox.netlify.com/). Then navigate different pages like homepage, /tags, /posts, etc to see how they change.

---

<div class="post-metadata">

**Author:** ![9999years](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/9999years/32/5671_2.png) [@9999years](https://discourse.gohugo.io/u/9999years)\
**Post date:** [April 8, 2018, 9:35pm UTC](https://discourse.gohugo.io/t/preview-actual-template-lookup-order/11443/4 "2018-04-08T21:35:58Z")

</div>

> [@bep](#):
>
> `hugo lookup content/section/xxx.md` would be contextual and that is not enough information to give one answer.

What other information is needed to determine lookup order, other than `config.toml`?

> [@bep](#):
>
> The examples in the docs are actually auto-generated. So they are correct.

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.

> [@bep](#):
>
> I think you really need to understand a few of the basic concepts to really enjoy Hugo

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

---

<div class="post-metadata">

**Author:** ![TotallyInformation](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/totallyinformation/32/5668_2.png) [@TotallyInformation](https://discourse.gohugo.io/u/TotallyInformation)\
**Post date:** [April 9, 2018, 6:13am UTC](https://discourse.gohugo.io/t/preview-actual-template-lookup-order/11443/5 "2018-04-09T06:13:42Z")

</div>

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](http://it.knightnet.org.uk)) [https://confident-carson-5eac42.netlify.com](https://confident-carson-5eac42.netlify.com), you will see some debug information in the sidebar.

---

<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:** [April 9, 2018, 6:16am UTC](https://discourse.gohugo.io/t/preview-actual-template-lookup-order/11443/6 "2018-04-09T06:16:10Z")

</div>

Perhaps this helps:

> [@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…

---

<div class="post-metadata">

**Author:** ![bep](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/bep/32/3332_2.png) [@bep](https://discourse.gohugo.io/u/bep)\
**Post date:** [April 9, 2018, 7:30am UTC](https://discourse.gohugo.io/t/preview-actual-template-lookup-order/11443/7 "2018-04-09T07:30:49Z")

</div>

> [@9999years](#):
>
> What other information is needed to determine lookup order, other than config.toml?
> 
> bep:

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.

---

<div class="post-metadata">

**Author:** ![9999years](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/9999years/32/5671_2.png) [@9999years](https://discourse.gohugo.io/u/9999years)\
**Post date:** [April 9, 2018, 2:50pm UTC](https://discourse.gohugo.io/t/preview-actual-template-lookup-order/11443/8 "2018-04-09T14:50:54Z")

</div>

Yes, I certainly agree that an event logger would be useful. A subcommand would be nice but obviously isn’t critical. Is [#4481](https://github.com/gohugoio/hugo/issues/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.