SOLVED: Single.html vs list.html

I’m confused about the difference between the single.html and list.html templates when my content is in a section (for example, content/post/

The template engine will look for a layouts/post/single.html template. It will also set the .Section to “post.”

When Hugo creates the summary for posts (the page that’s served at localhost:1313/post/), it doesn’t look in the layouts/post/ directory. It looks for a layouts/section/post.html template.

It also doesn’t set the .Section at all.

When I started looking, I realized that this was called out in the Content List Template documenation, but it is a surprise. I think that it makes sense to look in layouts/post/list.html since that parallels how single.html and list.html work in other directories.

Am I missing something about the design here?

You aren’t the first to be confused here. I think the confusion comes from a single behavior in Hugo.

If content type is not specified, the section name will be used as the content type.

This behavior comes from how people generally organize their content.

A section is the first directory under root. In your case it is “post”… we will call this postSection for clarification.

A type is assigned via the front matter. It’s entirely possible for a given section to have content of different types in it. For convenience purposes if a type isn’t defined it will take the section name as type… In this case “post”. We will call it postType for clarification.

For any given type Hugo looks in /layouts/TYPENAME/single.html to render it.

Additional views of that type can also be placed in that directory, for instance a summary view would be /layouts/TYPENAME/summary.html

When Hugo is called to render a section it looks for /layouts/section/SECTIONNAME.html .

While I did consider having Hugo look at TYPENAME/list.html, after some thought it was apparent to me that this would be even more confusing. Why would a type list need to handle content of other types. By keeping the layout for a section in /layouts/section it kept this separation which reinforced the idea that a section can contain many types.

I hope this clarifies things.


Thanks for the explanation.

Can you clarify why .Section isn’t set to “post” for the listing? This is related to the issue that @isaac brought up in “How to Check for Home Page?”

In this case it's called .Title. The data sent to the list template is a section, which has a title. The data sent to the single template is a page that has a section.

I’m struggling to understand views. My naive expectation is that each item of content may have one or more ways of being viewed - i.e. several views. I might have a single view of blog text, I might have a grid view of photographs, I might have a vertical table of multimedia clips, or etc I might come up with numerous other ways to arrange content on the screen.

I don’t understand Hugo’s view concept at all. Please would you spell it out in simple terms.

  • What are the input files?
  • What are the output files?



I think there’s a very subtle, but critical difference between the way you are thinking about it and the way it’s actually designed.

I would say it in a different way. “Each piece of content may be rendered in a few different ways”.

Let’s use an example to illustrate. I have two different types of content. 1. a blog post, 2. a project.

so in our example let’s also have one actually piece of content for each type.


Each has their own primary view which is their single page.


They also appear when listing all of the pieces of content… say in a taxonomy “tags”. In this case each type can define it’s own way of being rendered in this particular view… Let’s call it a “summary view”. The page that does the listing doesn’t care how each individual piece of content is rendered, but delegates that rendering to the content itself. In Hugo that translates to a “view”.

which would delegate the rendering of each piece of content to the “summary view” found at :

Hope that helps.

1 Like

Thanks for that. Could you clarify what files are generated in each case? I think that’s the missing link in my understanding.

/content/post/ + /layouts/post/single.html -> /post/one/index.html
/content/project/ + /layouts/project/single.html -> /project/two/index.html

Assuming taxonomy is called tags and both are assigned the term “go”…
/layouts/taxonomy/tag.html -> /tags/go/index.html

1 Like

That’s really helpful. Would you mind updating the online documentation with this clarification?

Also in the online manual, can I suggest that the taxonomy section should come before the theme section, straight after the content section. Taxonomies are referred to before the section that describes them. I found this confusing until I realised I had to read it not in order.

I think if you made such a pull request it would be both appreciated and accepted.

Hello dear Hugo community,

I am new to Hugo and I apologize for bumping this but the description fits my question exactly.

I am running a single page theme (hugo-creative-theme) and everything works fine on the main page, I am able to iterate through content, add it to the page as a partial and style the output using the .css in the theme. (I am aware that it is not wise to alter the theme’s own .css, but this is my first so bear with me :slight_smile:

In the list of upcoming events I added this snippet to show more than the excerpt :

       {{ if .Truncated }}
          <div class="read-more-link">
            <a href="{{ .RelPermalink }}">Read More…</a>
       {{ end }}

This opens /date/live/ that is generated by /content/date/ but no css is applied even though I called

<link rel="stylesheet" href="{{ .Site.BaseURL }}css/main.css" type="text/css">

from the /partials/header.html that is itself called from /layouts/date/single.html like in your example:

Also in verbose mode Hugo is telling me that he’s unable to locate layout for section date.

Am I missing something basic?

Since you structured your content folder like /content/date/whatever, Hugo expects that “date” is a section and looks for the template in the appropriate places (covered well in the docs).

As for the css I’d say: look at the source for the page and see what URL’s actually being called there. Why do you need the base URL anyway? Why not just hard link the css like: <link rel="stylesheet" href="/css/main.css" type="text/css">

Thank you for the clarification, as I mentioned I really am a newbie here. Actually formulating the issue and reading your comment helped me figure out what was wrong.

Sorry for the noise.

Glad it worked out @JazzVocalistMe . Definitely comb thru the docs if you have not had a chance to already. Lots of good info there, and here in the forum.