Index.md vs _index.md

#1

Sorry to dig up an old thread but I was just banging my head against Hugo for 2 days until I found this thread. Why is it that removing /content/index.md fixes this issue?

And why does using hugo new posts/mypost.md still generate the file?

That was an incredibly infuriating issue and no amount of using --verbose, googling led me anywhere until I gave Google the magic permutation to get here.

1 Like
Not generating any pages other than index
#2

Hi @keithers. I moved your post to a new topic and linked the old one since it’s already solved.

The reason it works is because index.md gets you a leaf bundle, which doesn’t allow child sections. So it must be changed to _index.md, which gets you a branch bundle, and does allow child sections.

I recommend digging into: https://gohugo.io/content-management/page-bundles/#readout

As for this, it may be because new pages have draft set to true by default. So either set draft to false, or run hugo server -D

1 Like
#3

Thanks for moving that for me!

That link helps a little bit in clarification by defining terms I wasn’t sure how to express, but I’m still a little confused as to the inconsistent behaviour.

Let me try and describe the situation a bit better:

  1. Say I have content/index.md.
  2. Running hugo will not build any of my content (also same if I use hugo server)
  3. Running hugo new post/mypost will cause the new post to be rendered.
#4

General stuff to know:

  • If you run hugo, it will build to /public in your project, per the templates that you have. If you have content but no template that matches, hugo won’t build it. Also @zwbetz mentioned the drafts thing.
  • If you run hugo server the default is to not build to /public but rather to memory. You can use a switch on that to make it build to /public.
1 Like
#5

@keithers - have a read of the link which @zwbetz shared above. It’s not an easy concept to get your head around (and you may want to search the forums for more stuff on leaf vs branch bundles).

The short answer is that files named index.md (or _index.md) do something special in Hugo. You should only use those names if you understand bundles. Your site may not need a file named index.md (it isn’t the same as index.html).

1 Like
#6

Yup, had a look at it. According to my understanding, having that leaf bundle (content/index.md) should cause my site to never build.

But the issue I was seeing was that I could get stuff to render by using hugo new. That’s the part that got me so confused. I guess it might just be some case that I shouldn’t be doing that anyway?

#7

I think that the most important docs to review are:

One thing to note: your Home Page (content/_index.md) is a special type of page (see: https://gohugo.io/templates/homepage/).

I also think that there are several issues being confused/coming together here and that you should take some time to review them:

  1. Content organisation (see above). I find the “Tree Metaphor” (i.e. branch vs. leaf) to be very helpful in how I think about how Hugo “sees” things.
  2. Template Organisation & Look-Up This directly springs from how Hugo sees things – how you structure your content files (and what you name them) directly connects to how you structure your template files and what you name them. This can be a major hiccup – and this is not bringing in templates specified in front-matter!
  3. Hugo commands hugo new ... creates folders and files – but you have to give those folders and files the “right” names and structures for any of the “rendering” commands (hugo serve ..., hugo build ...) to do something “predictable” or, at least, expected.

In general, I think that there is a lot of room for growth in the documentation about the “Templating” types/concepts and their connection to the content organisation. @zwbetz That was a great (new?) doc page which really nicely shows that that there are just two ways that Hugo “looks” at pages (is it a branch? is it a leaf?):+1:

1 Like
#8

That’s really helpful. It’s something I (and maybe other posters on this thread) hadn’t realised until now. I’ve just reorganised one of my sites to take advantage of the homepage template. I reckon it’s much neater than shoving everything in config.toml.

1 Like
#9

Yes, the great thing with Hugo is that it offers enough functionality that you can force it to do a lot – it might not be pretty, but you can coax it to do what you want. However, it is always good to do things in the “Hugonic” way which can have a very minimal set-up if you know how Hugo looks at things. I’m always in the process of simplifying my templates because I’ve realised that I’ve over-thought something.

1 Like
#10

( comment revoked as I made a misguiding statement in there )

#11

Really? Why?

I have a single page application that uses this exact setup /content/index.md.

Right next to the index.md there are various page resources in the form of markdown files as well as various folders with images that are fetched as image resources from within the /layouts/_default/single.html template. There is no index.html template or any other list templates in this project.

My understanding is that if one wishes to turn the entire content directory into a bundle for a single page application one can do just that by placing an index.md directly under /content/

P.S. I can give you access to that private project of mine if you want to take it for a spin locally and see with your own eyes. If you want to check it out then send me a PM @kaushalmodi

#12

You are correct! Apologies. Looks like I never experimented with a leaf-bundle-only site.

2 Likes