How do `layouts/_default/list.html`, `layouts/_default/baseof.html` and `layouts/taxonomy/tag.html` interact with each other?

I am going though Hugo by building a blog site and I am stuck at how layouts/_default/list.html, layouts/_default/baseof.html and layouts/taxonomy/tag.html interact with each other.

EDIT: the whole site is available at

The structure of my site is the following:

Specifically, layouts/taxonomy/tag.html is

Below is a list of pages with tag {{ .Page.Title }}

    {{ range .Data.Pages }}
        <a href="{{.RelPermalink}}">{{ .Title }}</a>
    {{ end }}

This correctly gives me the expected bare page, with the line `Below is …" and a bullet list of posts.

So far so good

I then wanted to style it the way the other pages are. They are based on baseof.html:

<!DOCTYPE html>
    {{- partial "head.html" . -}}
    <body id="site">
        {{- partial "header.html" . -}}
        <div id="content">
        {{- block "main" . }}{{- end }}
        {{- partial "footer.html" . -}}

In other pages (index.html or _default/about.html) I am just defining main and that block gets merged with baseof.html (at least this is my understanding and the result is as expected). For instance _default/about.html is

{{ define "main" }}
<main aria-role="main">
    {{ .Content }}
{{ end }}

I tried to do the same with layouts/taxonomy/tag.html:

{{ define "main" }}
Below is a list of pages with tag {{ .Page.Title }}

    {{ range .Data.Pages }}
        <a href="{{.RelPermalink}}">{{ .Title }}</a>
    {{ end }}

{{ end }}

The result is an empty page:


What is the correct way to merge such list templates?

(I am not sure actually where _default/list.html is in all of this - it seems it is not taken into account at all for the tags page above)

Mike Dane published a series of Hugo tutorials on YouTube.

Please spend a few minutes reviewing:

Don’t just watch. Do what he does, pausing the videos as needed. You’ll make mistakes, then you’ll have to figure our what you did wrong. Learning!

1 Like

Thank you @jmooring for the great references - they are indeed a good addition to the docs.

Now, and please do not take this as sarcasm or something, your answer is of the kind that if I asked for the chemical formula for water, you would redirect me to the Schrödinger equation, the Hilbert space and that this would ultimately allow me to find by myself that this is H2O.

I use lists, I read the docs all over to understand how that specific problem of layouts/taxonomy/tag.html works with layouts/_default/baseof.html because this is the only place which does not work as a main block.

It is probably a silly mistake or misunderstanding which can be fixed and then one can get the eureka moment which pushes them a bit further in understanding Hugo.

Again - I honestly thank you for the links but not everybody works the same way (I develop for 30 years so I read docs but sometimes going through an example is more useful)

Hi there,

baseof works with taxonomy/tag.html for me.

Please have a read about Requesting Help to see how to ask for help.

We need to be able to replicate your issue to be able to help you. Snippets are not usually very useful unless accompanied by site context. As for screenshots, whenever I see someone here post a question accompanied by one, my immediate assumption (and likely that of others’ as well) is that the poster is a newbie and also respond accordingly, usually with links to tutorials like the above.

As for example code, there’s plenty of baseof in the wild in the Themes section.

@pointyfar fair enough - I created a repo at and will update that in my question.

I am glad to see that layouts/taxonomy/tag.html works for you, there is hope for me :slight_smile:

As for baseof.html, that part is fine as it works with all my pages (single, lists), it is just taxonomy/tag.html which does not.

This line and all above it is the culprit.

See the note here.

Ah, you very much.

So the problem was that the included file must be strictly in the form of

{{ define "main }}
{{ end }}

with nothing else above or below.

It indeed now works when I removed the comment and the hello line.

It may be worthwhile to consider to maybe include that in the documentation. Initially I just had the comment line and it was enough to break the merge.

It is, BTW. See doc page linked above.

Code that you put outside the block definitions can break your layout. This even includes HTML comments. For example:

You are absolutely right. Not only it is present but it is highlighted.

It must be my reading skills - I had to actually do a Ctrl-F on the page to find it (despite being highlighted). It covers exactly the issue I was having.

Thanks again.

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