content: Describe/clarify use of identifiers in template file names

[jmooring]

See https://discourse.gohugo.io/t/partial-fallbacks/56157/22.

Also note that identifiers must be lower case (e.g., layouts/page.en-us.html instead of layouts/page.en-US.html. See somewhat related issue gohugoio/hugo#12829.

[irkode]

first results for a two token partial name "a.b"

WARN  We test the following partials (relative to /layouts/_partials):
[
  "two/myname.amp",
  "two/myname.foo",
  "two/myname.html",
  "two/myname.json",
  "two/myname.xml",
  "two/myname.missing",
  "two/missing.html",
  "two/missing.amp"
]
      LAYOUT               PAGE                 CALLED               USED
--------------------------------------------------------------------------------
WARN  home.html            /                    two/missing.amp      [ NONE ]
WARN  home.html            /                    two/missing.html     [ NONE ]
WARN  home.html            /                    two/myname           _partials/two/myname.html
WARN  home.html            /                    two/myname.amp       _partials/two/myname.amp
WARN  home.html            /                    two/myname.bar       _partials/two/myname.html
WARN  home.html            /                    two/myname.foo       _partials/two/myname.html
WARN  home.html            /                    two/myname.html      _partials/two/myname.html
WARN  home.html            /                    two/myname.json      _partials/two/myname.json
WARN  home.html            /                    two/myname.xml       _partials/two/myname.xml
WARN  sitemap.xml          /_sitemap.xml        two/missing.amp      [ NONE ]
WARN  sitemap.xml          /_sitemap.xml        two/missing.html     [ NONE ]
WARN  sitemap.xml          /_sitemap.xml        two/myname           _partials/two/myname.html
WARN  sitemap.xml          /_sitemap.xml        two/myname.amp       _partials/two/myname.amp
WARN  sitemap.xml          /_sitemap.xml        two/myname.bar       _partials/two/myname.html
WARN  sitemap.xml          /_sitemap.xml        two/myname.foo       _partials/two/myname.html
WARN  sitemap.xml          /_sitemap.xml        two/myname.html      _partials/two/myname.html
WARN  sitemap.xml          /_sitemap.xml        two/myname.json      _partials/two/myname.json
WARN  sitemap.xml          /_sitemap.xml        two/myname.xml       _partials/two/myname.xml

That's quite as expected:

• no partial with the same first token -> no template is found
• usage of known suffixes as second token -> the file is literally matched regardless of actual output type.

special case:

• expected? if the second token is missing or not a valid suffix (foo) -> the result is always "myname.html"

• strange??: I removed the myname.html partial -> the result is always myname.foo (which is no valid suffix)

  WARN  home.html            /                    two/myname           _partials/two/myname.foo
  WARN  home.html            /                    two/myname.amp       _partials/two/myname.amp
  WARN  home.html            /                    two/myname.bar       _partials/two/myname.foo
  WARN  home.html            /                    two/myname.foo       _partials/two/myname.foo
  WARN  home.html            /                    two/myname.html      _partials/two/myname.foo
  WARN  home.html            /                    two/myname.json      _partials/two/myname.json
  

[faraixyz]

So I got back to using Hugo after a while and yeah, the new identifiers are a bit confusing.

Just wanna note that these identifiers also apply to content views.

I used to have a generic li.html content view for how I wanted pages to be rendered out in a list.

The default li.html would be in layouts/_default/li.html and if you wanted a different one to be used for term pages, you'd put it under layouts/term/li.html.

With the new template system, the default is now at li.html with the term specific one at layouts/term.li.html. Interestingly, layouts/li.term.html works as well. Looks like li.term.html beats term.li.html, but I haven't checked thoroughly enough to understand the actual order.