Documentation on necessary steps to update templates

support
1

Hello,

trying the latest Hugo release I feel a bit lost regarding the template system changes.

From the bug tracker issue mentioned in the release notes, I was under the impression that it should be sufficient to rename the /layouts/partials and /layouts/shortcodes directories to /layouts/_partials and /layouts/_shortcodes and adjust the partials path in my template partials accordingly.

But Hugo complains: ... readAndProcessContent: ".../index.md:126:1": failed to extract shortcode: template for shortcode "fr" not found.

The file /layouts/_shortcodes/fr.md exists. Is there more to update and I should wait until proper documentation is in place? Or could this be an error? Thanks.

I’m coming from 0.145.0 BTW.

2

In most cases, that is true. But there are some edge cases. We consolidated all of the “template lookups” to follow the same code path. That means we also fixed a bug or two. One of them is that we don’t consider plain text templates for shortcodes when rendering HTML. This is a security related bug fix.

To get passed this, you either need to

  1. Rename the shortcode to e.g. `fr.html``
  2. Redefine the markdown output format and set isPlainText = false.
3

My apologies. That was a typo. The shortcode file is already named: /layouts/_shortcodes/fr.html

But at least this confirms that I’m heading in the right direction. I did not find any other instructions regarding the upgrade and was unsure because of the issue.

I use some external modules that I haven’t updated yet. So I fully expect that the build fails. But the only error currently displayed is the issue with the shortcode which should not be related, because the shortcode is part of the project itself. But maybe it’s still a consequence of the currently broken setup. I will check that.

As always, thanks much for your help!

4

OK, I read the above and thought differently.

OK, now I see it. OK, so this is a bug, I guess.

The thing is, for fr.html, we pares fr and html into language and media type, which does not make sense in this case.

See fr.html shortcode should be named fr even if the language is fr · Issue #13699 · gohugoio/hugo · GitHub

I will fix this in a release within a day or two. The only workaround I can think of is to rename the shortcode to something that isn’t also a defined language.

5

just to mention.

I have created _shortcodes/fr.html and it works … but it looks like a new shortcode is not found on server rebuild.

don’t remember if this was the case before

reproduce:

  • added a shortcode call to md file
  • hugo server server complains with exact the same message
  • add the shortcode.html to _shortcodes folder
  • the message persists re-saving the md does not help

after a server restart all is fine.

single en language site. name does not matter. at least with this site the ahortcode name en.html works. as fr.html

hugo v0.147.2-c7feb15d10b29a94d7fb57c31e8bcb2e92718fb7+extended windows/amd64 BuildDate=2025-05-06T11:18:55Z VendorInfo=gohugoio
GOOS="windows"
GOARCH="amd64"
GOVERSION="go1.24.0"
github.com/sass/libsass="3.6.6"
github.com/webmproject/libwebp="v1.3.2"
github.com/sass/dart-sass/protocol="3.1.0"
github.com/sass/dart-sass/compiler="1.83.4"
github.com/sass/dart-sass/implementation="1.83.4"
6

@Bep I see. Makes sense. The project is multi-language with both de, en and fr enabled in the settings. Thanks!

And no rush regarding a new release. At least for me, it can wait.

7

I assume you don’t have fr defined as a language.

8

right.

but the site is single language en. and an en.html shortcode works.

so might be a multilingual issue only

UPDATE TEST:

mmh, I took an example multilingual site from @jmooring

git clone --single-branch -b hugo-forum-topic-48029-multilingual-single-host https://github.com/jmooring/hugo-testing

converted the layout structure to:

LAYOUTS
│   baseof.html
│   home.html
│   list.html
│   single.html
│
├───_markup
│       render-image.html
│       render-link.html
│
├───_partials
│       css.html
│       language-switcher.html
│       menu.html
│
ADDED SHORTCODES 
└───_shortcodes
        de.html
        en.html

and both shortcodes render in en/_index.html called as {{< en >}} same for german (de)

1 Like
9

@bep Actually I didn’t have fr enabled. I forgot that in order to speed up rebuilding during development, the secondary languages were disabled in the development config:

_default/config.toml

defaultContentLanguage = "de"

[languages]
  [languages.de]
    weight = 1
    languageName = "Deutsch"
  [languages.fr]
    weight = 2
    languageName = "Francais"
  [languages.en]
    weight = 3
    languageName = "English"

development/config.toml

disableLanguages = ['fr', 'en']

It started working after enabling the languages. Hope that helps to reproduce the issue.

1 Like
10

corrected the cases:

same for me, I disabled de and the error occurs IF (default is en)

  • en/_index.md contains {{< de >}}

but not if

  • en/_index.md contains {{< en >}}
Error: error building site: process: readAndProcessContent: "C:\_repos\github\jmooring\hugo-forum-topic-48029-multilingual-single-host\content\de\_index.md:10:1": failed to extract shortcode: template for shortcode "en" not found
1 Like
11

I’m nearly done upgrading and I’ve ran into another issue, you might want to streamline (or document): I’m using configuration by convention for Hugo modules and check for a specific template to perform setup.

The code first looks for the partial and then tries to load it:

{{- $setup := (printf "_partials/%s/Setup.html" $name) -}}
{{- if templates.Exists $setup -}}
  {{- $data := (partial $setup (dict "ctx" $.Page "modules" $modules)) -}}
  ...

Turns out the templates.Exists call requires the full path, but the partial call fails if the _partials/ path prefix is present. I would prefer the same policy for both functions.

12

Also see New template system in Hugo v0.146.0

1 Like
13

Great! Thanks!

1 Like
14

This topic was automatically closed 2 days after the last reply. New replies are no longer allowed.