_index.md 'pages' in section/taxonomies etc are NOT rendered using single.html template

support
1

**

NOTE - The docs now include a full explanation of how to use _index.md files here:

https://gohugo.io/content/using-index-md/

**

From this thread I’d like to clear up some confusion I had in the hope it helps anyone who gets this particular case wrong like I did.

The matter relates to rendering the content of an _index.md file in a hierarchy like this:

content/post/_index.md

Remembering one thing - /post/ is a section and sections are rendered using list.html (or relevant section template) it makes sense that the single.html template is NOT used here because:

a) That’s what the docs say
b) That’s what the docs say

Seriously, I should have grokked it from the docs, but in my defence this page says:

To add content and frontmatter to the home page, a section, a taxonomy or a taxonomy terms listing, add a markdown file with the base name _index on the relevant place on the file system.

It gives the impression (to impressionable folks like me at least) that’s all you have to do.

But it’s not all you have to do.

You have to either ensure your default list.html file is written to ensure that it would render {{ .Content }} to actually render the content of the markdown page. Or you need to ensure you have a section layout (e.g. section/post.html) defined to do the same.

So, whilst technically ‘obvious’ that this is the case following the info in the docs it’s not completely clear that the _index.md content isn’t a ‘single’ page. It’s actually still a ‘list’ page as it’s being rendered at the root of a section.

So, don’t make the same mistake I did if you want actual content to render.

Incidentally, to head of any discussion on it - I for one am strongly against changing this behaviour. It’s current form is logically consistent with the template hierarchy and a simple clarification is all that needed IMHO.

A question on the official docs

What is the etiquette with updating docs on this project? Is anyone able to simply create a pull request with changes or are there guidelines in place to follow? I do not mind updating the docs to make this clearer to new folks (and slow ones like me :smiley: )

4 Likes
2

Updates to docs in the form of Pull Requests are always welcomed from everyone!

Note that

  1. I added the docs about the _index.md etc. after spending a fair amount of time implementing it, so it became a little of an after-thought
  2. What is clear and obvious to me, may not be clear and obvious to other users

I think we have an open issue about this doc needing a update.

3

This information was really helpful, thanks! I also misunderstood this behavior before.

1 Like
4

you’re a legend. i’ve spent several hours trying to work out why i can’t make a section work. I assumed, as i think you did, that stick _index.md into the section, and render using layouts//single.html.

5

yep - but

content/_index.md will be rendered with layout/index.html

6

@tathagatbanerjee

Hopefully this helps. It’s from the new docs concept. I’m open to feedback on how to make this clearer:

https://hugodocs.info/content-management/organization/#index-pages-index-md
https://hugodocs.info/templates/lists/#adding-content-to-list-pages

7

The old docs already have a page with a detailed explanation:

https://gohugo.io/content/using-index-md/

Including that and extending if necessary would be great as it gives much more in depth detail.

8

Thanks for the suggestion, @JoshArcher! It is included in the new docs but spread out in a few different areas. Having a page titled “Using _index.md” assumes that a new Hugo user will know that they should be looking for this. It’s also the very last item in the content section.

Instead, I opted to spread it out through the different areas of the docs-all the original content is there–where the user needs to know this information (e.g., in templating and content organization [as well as in example directory trees]). That said, I can probably mention it in a few more places to make it even clearer…

9

I’d be cautious about just doing this alone as this was done (in a less thorough manner mind you) before the above page was written.

There was a LOT of confusion about how to use _index.md files and what they exactly do. Having something readily findable in search engines and ‘in one place’ might be prudent. Either that or beefing up the headings in the newer docs to try and capture some search terms might work.

10

One other thing - having one place to send people struggling with this can also reduce the support burden of walking them through several sections where they have to gather info.

I understand the intent to provide them with the info they need in a logical manner so the hope would be they wouldn’t be confused in the first place, but if running my own docs has told me anything it’s users won’t read and will try to skip to stuff they think they need.

So having a ‘have a read of this’ type post like the one in the original docs may be more effective in practice, if less elegant in principle.

11

Good call. Have you compared the new docs search with the currently published site? I’m open to suggestions on how to improve the search experience as well, but for reference, the way I pulled up the above two links was by typing “index.md” into the new search :smile:

I agree. I remember answering a lot of questions here on the forums. The thing is that the current “Using _index.md” page is a great place to point people to if they’ve come to the forums and we’ve told them about the change. In the technical documentation world, this is already a bit of a loss. It should be explained thoroughly within the context of when the user is going to encounter or need it.

That’s my point: how would they know they need to read a page called “Using _index.md?”

It’s also referenced under the heading “Adding Content to Section Templates” (https://hugodocs.info/templates/section-templates/#adding-content-to-section-templates), which from what I can tell is the most common point of confusion for users (i.e., since fewer Hugo users leverage _index.md files for taxonomies and other list pages).

12

I’m not sure I have the right answer, or if there even is one, but with complex topics like this one I’ve found it reduces the support burden to come at the problem from two angles.

  1. Having the info in the docs in the places it should be in the hope that most people will see it and understand

  2. For particularly contentious/confusing topics that constantly come up - have an extra and dedicated in depth page.

Yes it may be redundant but it saves time overall for support ‘staff’ when a further reduction in those that are confused can be achieved with a simple ‘read this page for further in depth detail’.

Also a link along the lines of ‘see this page for in depth info on this topic’ can be added to the other sections which would solve the "how would they know they need to read a page called “Using _index.md?”.

What’s for certain is that the current docs discoverability on this topic isn’t working (so an updated/rework/greater visibility/rewrite would probably be a good idea anyway). I think the current top two posts here on the are regarding confusion over it. This one in particular:

Hopefully things like that thread will die down as we get further away from pre “everything is a page” but for now at least possibly having a dedicated page with info worked into the ‘right’ ares of the new docs could help.

13

Agreed. The current docs include the “Using an _index.md” page. The current site definitely needs that page, but the new site doesn’t. For the record, I think it was a great addition, so thank you.

You might want to dig around https://hugodocs.info a bit more. It’s not just a reorganization of files or a new theme. Parts of the docs have been changed considerably. For example, the “Extras” and “Tutorials” sections have gone the way of the dodo bird.

Nevertheless, I’m glad you brought this up. I just reviewed the page for the homepage template and realized there were opportunities for improvement. I’ve already pushed them to the live site:

https://hugodocs.info/templates/homepage/#adding-content-and-front-matter-to-the-homepage

I also think I should add a similar heading and page section to the taxonomy templates page. Stay tuned.

Oh, and if you have anymore feedback, would you mind adding an issue to the Hugodocs.info GH repo or possibly replying to the following thread instead? I feel like we’re hijacking this one a bit. :smile: Thanks!

14

Ha, thanks. It’s a sticking plaster for sure as the way to ‘solve’ it is to surely do what you’re doing with a full rewrite. I guess I just know some people don’t really read anything at all anyway so hey, why not at least try and do it this way for those that do? (the right way I mean) :smiley:

I’ll take a closer look. Rewriting parts alleviates much of my concern as an overall response to this particular topic, I guess we’ll just have to see when it goes live if any adjustment is needed. As long as you’re open to that there can be little harm.

I’ve just started watching the repo so I’ll chime in when time allows me.

1 Like
15

mate, sorry to be blunt. I simply don’t know enough about Hugo yet to give you an answer to that question. @JoshArcher post helped me with the immediate problem i was having, but can’t give you a good opinion on more than that.

Thanks so much.

Tat

16

I tryed to use the [outputs] section in config.toml.

[outputs]
home = [ “HTML”, “RSS” ]
section = [ “HTML”, “RSS” ]
page = [ “HTML” ]
taxonomy = [ “HTML” ]
taxonomyTerm = [ “HTML” ]

The /layouts/taxonomy/tag.terms.html will not rendered.
Commenting out this section all works like it should.
Any suggestions?

Thanks