How does fronmatter property "layout" relate to layouts subdirectories?

support
,
1

I’m trying to create different “page.html” templates for different sections.

Starting with my about page, I added {“layout”: “about”,…}and then created a subdirectory in my layouts folder layouts/page/about.htmlwhich worked fine.

Then I added {“layout”: “event”, …}to the bulk of the content files and put the template file in layouts/page/event.htmlwhich caused an error

WARN found no layout file for “html” for layout “event” for kind “page”: You should create a template file which matches Hugo Layouts Lookup Rules for this combination.

Moving the template event.html directly into the layouts directory rather than putting it in the page subdirectory sorted this problem.

But I’m still completely confused how one should organise the layouts directory. I know there’s a transition to moving basic templates from layouts/_default to directly in layouts/, but I’d like to organise by templates by section. I have no idea if the best practice is layouts/section_name/page.html etc or layouts/page/section_name.html, and also why this works for some and not others.

A difference between the about page is it’s in content/about/index.md whereas the event pages are in content/section_name/page_name/index.md, but their “kind” is both page.

2

That was deprecated in Hugo v.0.146.0

3

My interpretation of the documentation is layouts/about/page.html and layouts/event/page.html should do what I want, but they don’t.

4

There’s no relation between layout front matter and sub directories. That value maps to the first identifier in a layout file’s name, e.g. mylayout in mylayout.html.

5

For the site I’m building now, there aren’t many different page layouts, so layouts/event.html with corresponding {“layout”: “event”,…} in the frontmatter content/whatever-section/whatever-page/index.mdworks fine.

But for a more complex site needing a wide variety of page templates, some illustrative examples on how to use page paths would be nice.

I’m about to move on to writing my taxonomy on term templates, so bound to be asking questions about their naming conventions under the new layouts system soon.

6

But it is better to share your Git repo to reproduce what you are doing.

7

Just a general comment:

  • I have seen many (and built some) Hugo sites; and I have always thought of the layout front matter as something you would use for the the rare cases where you wanted something very different.
  • One of the most frequent questions about this before v0.146 was about how to style nested sections/pages differently than the rest.
  • So, in v0.146 you can nest your templates reflecting your content structure, which is very powerful.
  • That way you can have mylayout(as set in front matter) look differently depending on the content path.