How to define layout in frontmatter

support
1

This doc page has all the examples on how to match pages to a certain layout. However, it is doesn’t say much about rules about the Layout frontmatter variable.

Is this documented anywhere? If not, I am glad to contribute to this page, but first I would like to know about the frontmatter Layout variable and how it works.

1 Like
2

layouts/_default/mylayout.html will be used if your frontmatter says layout: mylayout.

1 Like
3

short sample in section Photo"

+++
categories  = ["Photo"]
date        = "2019-04-20T15:00:00+02:00"
description = "View on the river"
tags        = ["2018","Meissen", "Panorama"]
title       = "River Elbe near Meißen"
layout      = "panorama"
+++

template is layouts/photo/panorama.html

3 Likes
4

Relevant docs:

The only thing I would add to those docs is that the VIEW mentioned in those docs can be overridden with the layout frontmatter. By default a page will use either the section or list view layouts/_default/list.html or a single page or post view layouts/_default/single.html.

@martinjagodic Can you send a PR to the Hugo docs repo adding this clarification on layout frontmatter and View relationship?

@davidsneighbour @jmooring Can you add more clarification to this?

3 Likes
5

The thing to know here is, that if there is a layouts/_default/panorama.html and a layouts/photo/panorama.html then the one in layouts/photo overrides the one in layouts/_default. The more specific it gets (as in section-layouts-subfolder vs. default-layouts-folder) the higher the priority of the layout is.

And, @kaushalmodi yes, that needs to be in more places in the docs.

2 Likes
6

@davidsneighbour are you sure that for a file at content/photo/panorama.md the layout at layouts/photo/panorama.html would be an automatic fit? Because it doesn’t work for me.

It also doesn’t work if there are layouts named different than the predefined (like list and single). For instance, if I set layout: panorama in a /photo section, it will not find the layout at layouts/photo/panorama.html, only the on in _default folder.

7

Well… it SHOULD work. The problem is, that other layouts may override the chosen one. That whole layout selection thing in Hugo is not only very versatile, it’s also “too” versatile as in you might accidentally override the layout you want to use with another one that is higher up the list.

Long story short: share a sample repo with your layout that does not work and we will (probably) find the culprit.

@davidsneighbour are you sure that for a file at content/photo/panorama.md the layout at layouts/photo/panorama.html would be an automatic fit? Because it doesn’t work for me.

with no other layout file in place yes. With other files in place they might override this. It’s not the “if it’s there it’s 100% the one taken” but the one that is used if there is nothing overriding it.

8

@martinjagodic

if layout which is not in _default folder isn’t it obvious it is not going to apply?

here is what works for me

page layout works
photo/index.md _default/photo.html Yes
photo/index.md photo/single.html Yes
photo/index.md photo/panorama.html No

why you expecting layouts/photo/panorama.html apply to content/photo/panorama.md?

your content/photo/panorama.md will generate example.site/photo/panorama/ your are not any more in /photo since you have generated another folder photo/panorama/

hope this was helpful thanks