How does hugo relate a .md file to a html layout file?

Forgive me if this is the most blindingly obvious question one could ask, but I haven’t seen a clear statement within the documentation as to how hugo applies a template to a particular .md file.

My goal is to create a section overview/summary which lists the subsections within it, allowing someone to click on these and then see the relevant posts.

For example if I had:


I would want a visitor to click on “Art” and see Landscape and Portrait as their options on which they could click to navigate through to all the posts in that particular section.

I’ve followed the Content types documentation and created a layout/projects/art folder with a single.html and list.html files as well as adding an file in archetypes as per details.

When changing the default list or single.html sections in these areas nothing happens to my pages, they only utilise the _default list.html and single.html sections in the original theme and I’m not sure why.

Basically, I’m asking if anyone has a simpler way of explaining how a page chooses what layout it will use because I can’t get my head around the documentation.

This is a common problem for Hugo users. But we cannot do this general type of support here in the forum. If the documentation does not do the job, then that documentation needs to be improved.

@rdwatters is doing a job of redoing the documentation. I suggest you contact him directly and give him your inputs. I can only give you one general advise: Read the tempalte parts in the documentation again and then once more, and look at example sites.

For future reference. Here is a thread for new docs feedback. Thanks @bep: