The secret to productivity? Block internet distractions. Learn more about Cold Turkey Pro »

How to fix Hugo’s ‘unable to locate template for shortcode’ error?

Situation: You generate a static website with Hugo and got the ‘unable to locate template for shortcode’ error. You’d like to know what that message means and how to fix it.

Discussion: understand Hugo’s ‘shortcode not found’ errors

The ‘unable to locate template for shortcode’ error message happens when Hugo cannot find a shortcode we reference in a content file (GitHub, 2018). A shortcode is a snippet inside a content file that calls a built-in or custom theme template (Hugo Docs, 2017). They make it possible to embed small, reusable Hugo template code inside our content files (Hugo Docs, 2018).

The ‘unable to locate template for shortcode’ error message looks like:

ERROR 2018/01/27 11:07:34 Unable to locate template for shortcode 
    "latest-posts" in page "post\\hans-zimmer-nominated-grammy.md"

Errors like these tell us a couple of interesting things:

Let’s see what might cause the ‘unable to locate template for shortcode’ error.

Cause 1) Typed the wrong shortcode name in the content file

There’s a strong relation between how we name our shortcode template file and how we reference it in our content file: we have to use the shortcode’s exact name when we reference it in our content file (Hugo Docs, 2017).

So when our shortcode template is named latest-posts.html, there are only two ways to include it in a content file:

{{< latest-post >}}
{{% latest-post %}}

If we make a typing mistake with the shortcode, Hugo won’t be able to find it and trigger the error. Luckily, the Hugo error message already includes which shortcode name we tried to use in which content file. That makes it easy to locate and fix those spelling mistakes.

We don’t use a file extension when we include a shortcode in our content file. But if we include a partial in a theme file, we always have to the file extension. If we accidentally use a file extension with a shortcode, you’ll also see the ‘unrecognized character in shortcode action’ error on the command line.

Cause 2) Include a shortcode with single or double quotes

To include a shortcode file in our Hugo content file we provide the shortcode’s name without single (') or double (") quotes (Hugo Docs, 2017). This differs from how we, for example, include partials in our theme files, which do need double quotes.

And so with a disqus.html shortcode file, we include it in content as {{< disqus >}} or {{% disqus %}}. But not like this:

{{< "disqus" >}}

When we use shortcodes in this way, we’ll not only get the ‘unable to locate template for shortcode’ error but also an unrecognised character error:

ERROR 2018/01/28 12:50:01 post\hans-zimmer-nominated-grammy.md:12: 
    unrecognized character in shortcode action: U+0022 '"'. 
    Note: Parameters with non-alphanumeric args must be quoted
ERROR 2018/01/28 12:50:01 Unable to locate template for shortcode 
    "" in page "post\\hans-zimmer-nominated-grammy.md"

When you get these two Hugo error messages, check to see if you don’t accidentally called a shortcode with quotes.

Cause 3) Uncommon characters in the shortcode’s filename

The name of the actual shortcode file has to be something Hugo can understand when we include that shortcode in our content files. Unfortunately, there’s no list of accepted characters for the filenames of shortcodes. But alphanumerical characters (‘a’ to ‘z’ and ‘0’ till ‘9’) work fine.

For more uncommon filename characters there’s a chance Hugo has trouble with the shortcode. Say we have a latest;content.html shortcode file and try to include it in our content file like so:

{{< latest;content >}}

While the Windows operating system accepts the latest;content.html filename, Hugo cannot parse latest;content as a shortcode name and instead looks for the ‘latest’ shortcode:

ERROR 2018/01/29 12:11:17 Unable to locate template for shortcode 
    "latest" in page "post\\hans-zimmer-nominated-grammy.md"

To fix these errors we’ll need to rename the shortcode file. Since Hugo does accept a dash (-) inside a shortcode filename, latest-content.html would be an option here.

Cause 4) Hugo’s shortcode file in the wrong theme folder

To successfully include a shortcode in a content file, it needs to be in the theme folder where Hugo looks for it. There are two places where we can store a shortcode file (Hugo Docs, 2018):

But even when our shortcode file is somewhere in /shortcodes/, we can still go wrong. That’s because Hugo does not look in subdirectories of these folders for shortcode files. Instead, we should put shortcodes at the top level of /shortcodes/. And so this shortcode attempt doesn’t work:

{{< "/posts/latest-posts" >}}

{{< /posts/latest-posts >}}

Instead of including the latest-posts shortcode from the /posts/ subdirectory, we end up getting the ‘unable to locate template for shortcode’ error. We fix that when we move our latest-posts.html shortcode from the subdirectory into the /shortcodes/ folder.

Cause 5) Using a mix of <, >, and % to include the Hugo shortcode

There are only two valid ways to embed a shortcode in our content file (Hugo Docs, 2017):

The difference between these approaches is the following. Shortcodes we include with the percent sign (%) can have content between them that Hugo processes as Markdown (Hugo Docs, 2017). With the greater than and less than signs (< and >) we simply include the shortcode, and that’s all. For example:

{{% note %}}The content inside this *shortcode* gets
processed as **Markdown**.{{% /note %}}

{{< latest-posts >}}

Whether you include a shortcode with {{ and % or < and > depends on your goals with the shortcode. But we shouldn’t combine both like so:

{{ % latest-posts > }}

When we do something like this, Hugo throws the ‘unable to locate template for shortcode’ error. To fix it, we have to choose for % or use < and >.

Learn more

References

GitHub (2018, January 28). hugolib/shortcode.go. Retrieved on January 29, 2018, from https://github.com/gohugoio/hugo/blob/master/hugolib/shortcode.go

Hugo Docs (2017, October 27). Shortcodes. Retrieved on January 28, 2018 from https://gohugo.io/content-management/shortcodes/

Hugo Docs (2018, January 10). Create Your Own Shortcodes. Retrieved on January 28, 2018 from https://gohugo.io/templates/shortcode-templates/