What is the difference between _index.md and index.md?

1

I couldn’t find the difference of these two files described anywhere in the docs. They certainly seem to exhibit different behavior based on my testing.

I am talking about having a file in /content/pages/_index.md versus /content/pages/index.md

It sort of goes over it here: https://gohugo.io/content-management/organization#index-pages-index-md but I still don’t understand.

2

We have a docs page in draft mode which explains this, but It is hard to find the right terms for this.

  • “index.md” is a regular page which can contain other pages, images etc. as resources Basically all files in the same folder and below will be part of a bundle.
  • “_index.md” is the content page for the list type of pages, i.e. pages that has children – home page, section page, taxonomy lists and taxonomy terms. These can contain resources in the form of images, JSON files etc., but not other pages. And the bundle is restricted to the same folder level.
2 Likes
3

Here’s the draft documentation for bundles that explains index vs _index, but note that as @bep said, the terms used in there are not official. I used the leaf/branch terms as they made the most sense to me, and fit perfectly well with the leaf node and branch node terms from Tree data structure.

1 Like
4

Thanks that really clarifies things after reading it over a few times.

Is it possible to disable the index page for a particular section but not for others? As that is what I was originally trying to do. So far I have tried adding disableKinds = ["section"] to my config file but that disables the section index for all sections instead of just one. I also tried setting headless: true in index.md but that has the effect of not rendering any of the nested pages either.

5

Feedback is welcome regarding what should be clarified to make that doc easier to follow.

I doubt if you can do that. But what are you trying to achieve eventually. It would help if you can share your source, and explain using that what your end goal is i.e. why do you want to disable index pages for only some sections?

Headless or not, none of the nested pages in a “leaf” bundle will get rendered. A headless bundle simply becomes “invisible”… and that bundle’s resources can be extracted only via something like in that doc’s example.

6

Feedback is welcome regarding what should be clarified to make that doc easier to follow.

Sorry I didn’t mean to say that was a flaw of the documentation, just the wrapping my head around the subtleties.

I doubt if you can do that. But what are you trying to achieve eventually. It would help if you can share your source, and explain using that what your end goal is i.e. why do you want to disable index pages for only some sections?

I have a section called pages that has misc content like about and contact pages that I do not want to have a section for, then I have a few other sections like blog and services that I do want to display an index for.

7

It’s still very unclear without seeing the source…

A lot of assumptions need to be made without seeing the source.

a section called pages

So it’s content/pages/?

that has misc content like about and contact pages

Those 2 are about.md and contact.md? Or about/index.md? Or about/_index.md (shouldn’t be this last one).

that I do not want to have a section for

If you don’t want a dir to become a section, make it a “leaf” bundle i.e. put an index.md in that dir. That will then show up as a regular page.

then I have a few other sections like blog and services that I do want to display an index for.

So, what happens right now with those? how are those folders organized? Do they not have _index.md in them?

So you see… there are a lot of questions… You can get more and accurate help only after you share the site source (doesn’t have to be actual if there are privacy reasons… but at least share a minimal replica of that).

8

So if I have this correct. I am having an issue where my old docs site with index.md as the head content file no longer displayed the menu with the latest version of Hugo (see here). The “fix” was to convert the index.md files to _index.md. This fixed the menu issue, but the content of the top level menu items no longer displays in the browser. If I have read this topic correctly, that is the correct behaviour? So how do I have the content in _index.md showing in the browser? Do I create an index.md file in the same content section?

docs_issue
docs_issue.gif2540×938 1.34 MB

9

The source code is here: https://github.com/eberkund/yellowbirdie

If you don’t want a dir to become a section, make it a “leaf” bundle i.e. put an index.md in that dir. That will then show up as a regular page.

This turned out to be the solution. I guess there isn’t a way to get the same effect without creating folders for every page?

10

In the end, we solved this by renaming the index.md files to the same as the directory they are contained in. For example, the directory “getting-started” has the former index.md renamed to getting-started.md. This worked for us. So I’m so a bit baffled about the use of index.md and _index.md now? :slight_smile:

1 Like
11

That’s what I did as well @marksouthee :slight_smile:

_index.md is for when you have multiple pages under a folder like blog.

12

… or when you want to add metadata to a taxonomy term.