Only layouts/_default/list.html will work for my post section


i had a section list question. Thanks in advance.

For single site it works with \themes\THEME\layouts\post\single.html

But for the post list only ...\_default\list.html works.


Info: hugo.exe v0.14 Windows

The way I understand the documentation, a custom post list should be placed in:


I have the same problem. Using li.html (for the section) instead of list.html doesn’t change it. And in _default only list.html works (li.html doesn’t).

Hugo v0.14 on Linux.

If you launch hugo with the --verbose option you see where it’s looking for. In my case:

WARN: 2015/07/29 Unable to locate layout for section concerti: [section/concerti.html _default/section.html _default/list.html indexes/concerti.html _default/indexes.html theme/section/concerti.html theme/_default/section.html theme/_default/list.html theme/indexes/concerti.html theme/_default/indexes.html theme/section/concerti.html theme/_default/section.html theme/_default/list.html theme/indexes/concerti.html theme/_default/indexes.html theme/theme/section/concerti.html theme/theme/_default/section.html theme/theme/_default/list.html theme/theme/indexes/concerti.html theme/theme/_default/indexes.html]

As explained in the documentation, you should use:


In my website it will be /themes/THEME/section/concerti.html.
In yours it should be \themes\THEME\layouts\section\post.html.
Words in capital must be replaced of course.

A few things to help you work through this though maybe you already noticed:

  • you can override any theme templates or views by copying them to your site folders. If your theme has a /theme/thethemename/layouts/section/post.html for example, you can copy that to /layouts/section/post.html and edit it there to override.

  • per Hugo is searching for a section template in a specific to general way, starting at the top and moving down, rendering the most specific one it can find.


… if it doesn’t find /layouts/section/SECTION.html it tries /layouts/_default/section.html, and so on.

  • A theme may or may not have specific templates. If it does not you can specify one in /layouts/ and Hugo will use it. If it existed in the theme, your copy will serve to override the theme’s.
  • This page shows two sections, posts and projects, with views li.html, summary.html. You can access those from your list templates by doing {{ render "li" }} or {{ render "summary" }}.

Of course if you are building a theme, it’s a different matter and you should just include all the stuff your need within your theme. By override above, I meant when you are using someone’s theme as a base and needing to override bits of it.

One cool trick is to pipe an html comment to safeHTML, so that your page source will include a start and stop memo. That way you can see what template is getting rendered where.

{{ "<!-- ENTERING layouts/_default/li.html -->" | safeHTML }}
<article class="post">
<i class="tiny mdi-action-label-outline blue-text text-accent-3"></i> <a href="{{ .Permalink }}">{{ .Title | markdownify }} {{ if .GetParam "draft"}}{{ ( index $.Site.Data.translations $.Site.Params.locale ).taxodraft }}{{end}}</a> <span class="grey-text text-lighten-1">{{ .Date.Format "2 Jan, 2006" }}</span>
{{ "<!-- ENTERING layouts/_default/li.html -->" | safeHTML }}
1 Like

Out of curiosity, is there a reason that specific list templates have to be placed in /layouts/section/SECTION.html instead of supporting /layouts/SECTION/list.html just like how single templates are supported via /layouts/SECTION/single.html? I had skimmed over the list template documentation when writing a couple of different section templates and had to go back to check why /layouts/project/list.html wasn’t working and that I should try /layouts/section/project.html instead.

I’d much rather have all of my layouts for a section in one directory (like _default) than placing list templates in /layouts/section/SECTION.html.

1 Like

@spf13 seems to answer this one here:

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 am so far unable to get hugo to use layouts/section/section.html

I am not trying to create a type, but rather a plural url to render a list of the singular url, For example

/program —> all the type program single pages
/programs —> the list of programs

It seems to use the theme list.html if I make a content file in content/programs/, but its using the themes list.html and I am unable to get it to get hugo to use my copy in layouts/programs/programs.html

Or it might even be nice if I was able to change the themes list to not have the type hardcoded, but it seems the .Type var is not available and its of type node. I must be missing something here… Thanks for any reply.

Actually I worded that a bit wrong, program is a new type, but the themes list.html hardcodes the type “post”


Thanks. I knew it was something simple. I was reading the docs as “section” meant to replace it in the path as the name of the section I wanted, not literally a folder called “section”. Thank you for the reply!

1 Like