Proposal: Phase out `partial` lookup without suffix


Since about 2017 (per this discussion) users have been unwittingly using partial partialCached (and likely inline partials) without including an extension.

For example, using {{ partial "example" . }} should actually be {{ partial "example.html" . }}


  1. Difficulty for contributors supporting a mistake both on current and future features (from this @bep issue comment):
  • We support partial lookups without suffix for historical reason, and that was a mistake we cannot take back
  1. Users can have hidden issues. For example, while minor, Duplicate entries in templateMetrics


**Phase out historical partial, partialCached, and likely inline partials without including a suffix of the extension

A possible implementation could be similar to @cshoredaniel’s comment on issue 9603:

I wonder if we could make this a WARN or ERROR — I was unaware that not using .html was not best practice, in fact I thought the opposite was true (that is that it was better to avoid the .html ) — by default, and have a config option to increase to fatal, and/or remove the warning.

Perhaps this could be just a WARN and maybe a slow depreciation.

1 Like

In hopes of contributing a tiny bit towards helping others, I’ve open up PRs for the hugoDocs and gohugoioTheme repos

1 Like

Actually there was a comment by Bep recently on an issue on Github about that (not sure if that is in your links). It’s unintended but a feature - the gist of it. I made it my own rule to always have an extension in any partial call for a while now. I DO NOT think you will be able to get this made into a “feature” (the phasing out), but maybe having some form of bash script that checks templates and complains about missing file extension and linking to that post every time the topic will come up might help adding some “hygiene” to the issue and future layout samples.

I guess a first step is to go through the docs site and add extensions to all samples of partial and partialCached.

Yes, and it’s so old that we cannot remove it.

This is an example of a “we can be a little flexible here, how can that hurt?” … and then some years later.

This is an example of the main lesson I’ve learned working with Hugo. Flexibility comes at a cost and should be really important or be obviously without future negative side effects.


This would impact a lot of projects in the wild I’m guessing. On a related note, how does Hugo decide which partial to call when using {{ partial “components/example” . } when components/example.html and components/example.js both exist? Is there a lookup order for partials? (Docs are giving a 503 right now so I apologize if its’ mentioned already)

A partial without suffix is currently the only way to use ONE partial definition across MULTIPLE Output Formats.

Here is a detailed use case:

The Duplicate entries in template Metrics issue really does not outweigh current behaviour in my honest opinion.

Also it is much more flexible to have a project without duplicating template code per output format.


Ah. In that case maybe the definition of what is ‘best practice’ needs to be more clearly considered and articulated. In fact, I wonder if partialCached requiring .html is what could be considered a bug in light of this consideration.

1 Like

This may have been true at some point, but unless I’m missing something it is not true today.

git clone --single-branch -b hugo-forum-topic-30244 hugo-forum-topic-30244
cd hugo-forum-topic-30244
grep EXAMPLE public/index.html
grep EXAMPLE public/index.txt

This example has two output formats, with a home page template for each format. Each template makes this call:

{{ partial "example.html" }}

Actually it works in Hugo today.

The partial template should be under:

(no suffix in the filename)

The template call should be:

{{ partial "example" . }}

There are 2 Output Formats in my project HTML & RSS.
The example partial is outputted in both.

Try it and see with your own eyes.

P.S. I didn’t test your sample repo as my time is limited (I had to post in this topic though, since I really care about the current behavior and I don’t want to see it changed).

I did not say that you must provide an extension, though you should.

I am, however, disagreeing with this statement (emphasis mine):

So, requiring or recommending that users always specify an extension will not remove functionality.

How are you going about with minimising code duplication across different output formats?

In any case I am not recommending anything.

I’ve found that if I need to update a template frequently and keep it as a single file for all Output Formats, then the above method is the simplest that I’m aware of.

Unlike shortcode or layout templates, partials templates are not aware of the current output format. There is nothing to duplicate.


That’s interesting. I do distinctly remember that I was not able to output a .html partial when called from an RSS template back in Dec 2020, hence the above.

However you are right.

1 Like