How to defined custom layout after v0.146.0

support
1

Now I refered the target template from Hugo document wich link URL is : target-a-template, but when I tried after that found it not work of layout paramter on post’s front matter. You can see the detail code on hugo-feature-target_template.

So is it my mistake?

2

The new system is described here: New template system in Hugo v0.146.0

type in frontmatter

The type set in front matter will effectively replace the section folder in Page path when doing lookups

so if you set the type of a Page in front matter to type: 'customtype'

the layout will be /layouts/customtype/page.html

layout in frontmatter

The identifiers that can be used in a template filename are one of the [Page kinds] …one of the standard layouts (list , single , or all ), a custom layout (as defined in the layout front matter field)

so if you set layout: 'customlayout' in frontmatter

the template will be /layouts/customlayout.html

There might be more possibilities using folder pathes, but guess it’s a starting point for you

3

Hi @irkode , thanks for answer. And I check my test codehugo-feature-target_template that sure it same as what you said. But when I add layout in the front matter field. It’s not worked.

the code struct as below:

themes/hugo-next-v5/layouts/
├── baseof.html
├── custom
│   └── page.html
├── home.html
├── page
│   └── custom1.html
├── page.html
├── _partials
│   ├── footer.html
│   ├── head
│   ├── header.html
│   ├── head.html
│   ├── menu.html
│   └── terms.html
├── section.html
├── taxonomy.html
└── term.html

then add the layout field on the content/posts/custom1.md front matter like this:

---
date: '2025-05-21T22:18:43+08:00'
draft: false
title: 'Custom Layout'
layout: 'custom1'
---

This is use `layout` on post front matter. 

Yeah I can defined My custom page layout.

And the content struct is here:

content/
├── custom
│   └── first.md  # work fine
├── _index.md
└── posts
    ├── custom1.md # not work
    ├── _index.md
    ├── post-1.md
    ├── post-2.md
    └── post-3

Aslo there have a question: Is there use page.html instead of single.html ?

All above codes I had created run on Hugo CLI build.

4

rechecking…

5

not really same - small things matter :wink:

you page is in /content/posts/custom1.md with layout set to custom1

you expect it to use /layouts/page/custom1 but you don’t have any section named page so that template is not considered for a page stored in posts (-- and in fact you should not name a content folder after a page kind)

Change your layout to /layouts/custom1.html or adding the section /layout/posts/custom1.html if you want to target the section.

second question

page is a Page kind whereas single is a Standard Layout for a Page. I’m not in the details and docs quite brief, but in normal use cases I think you may use either of these.

reading the example structure in the docs:

>├── term.html
>├── term.mylayout.en.rss.xml

untested:
guess you could do something like: layouts/page.single.htmland layouts/page.custom1.html to but not the other way round. (and maybe layouts/posts/page.custom1.html)

6

@irkode Thanks for your rechecked. And I had tested your suggest as below then got the expected layout things.

And sure that page.html file is newest defined by Hugo latest version designed. So that why I tried use the page folder to save custom layout, because I guss it was by design. And now I know it need use page.xxx.html format to design your custom layout.

Thanks.