content/_index.md is not displaying on homepage

[SpencerDub]

The documentation indicates that you can display content on the homepage by making a content/_index.md file.

My content/_index.md contains:

---
title: "Lorem Ipsum"
draft: "false"
type: "page"
---
This is a test!

However, when I run hugo serve, nothing of the above is displayed on the homepage, except the site title.

I do not presently have an avatar nor social links defined, and I have not set the showPostsOnHomePage parameter.

I have also tried this with no frontmatter. I have tried hard-refreshing the tab with the site in it, as well as restarting the Hugo server.

What am I missing about displaying content on the homepage?

[mo65535]

That section of the Theme Documentation - Basics must be out of date. The Theme Documentation - Advanced page indicates that the file should be content/index-about.md. Since documentation can go out of date like this, sometimes your best bet on this sort of issue is to check the source. Looking inside the template file, we can see where it's pulling data from.

Using the correct filename may not be enough to solve your issue, though. For my local development setup [1], when I save changes to content/index-about.md with the Hugo server running, it prints to the console that a change in that file was detected and it claims to rebuild the site, but it doesn't reliably cause those changes to be reflected on my refreshed homepage. Sometimes the changes show up in the rebuild, but usually not. The workaround I've settled on is to save my config.toml file (don't have to make any changes to it, just update the modified time) which triggers a rebuild of the homepage, pulling in any changes that were made to content/index-about.md. Best of luck!

[1] Windows 10, hugo v0.123.1-3f8434a62fc91a50f4e5bd43a4435d2d301844ff+extended windows/amd64 BuildDate=2024-02-21T08:17:45Z VendorInfo=gohugoio

[526avijitgupta]

@SpencerDub Thanks for reporting the issue. As @mo65535 correctly pointed out, the basic documentation is outdated and mentions the incorrect filename. The PR to use the correct filename is under review, should be fixed soon :)

[SpencerDub]

Thank you both; updating the filename fixed the issue. I appreciate the help.

[jamesericdavidson]

Hi all,

I originally implemented this feature (#119, #109) and curious why the filename was changed to index-about.md?

_index.md has special meaning in Hugo, and IMO should be preserved for interoperability (primarily enabling users to freely swap between themes without the burden of re-configuration):

https://gohugo.io/content-management/organization/#index-pages-_indexmd

https://bwaycer.github.io/hugo_tutorial.hugo/content/using-index-md/

https://discourse.gohugo.io/t/what-is-the-difference-between-index-md-and-index-md/10330/2

[jamesericdavidson]

Commenting here again for posterity, and in lieu of opening a new issue.

I believe @yashmehrotra was originally considering reverting to _index.md, but we still have index-about.md today.

index-about.md was introduced in #179, and _index.md was removed in #181.

As stated in https://github.com/526avijitgupta/gokarna/pull/187#issue-1780624476:

... the gokarna theme already allowed displaying content on the landing page by creating the file content/_index.md, as described in the documentation. As far as I understand it there's currently no real difference between the two.

I've made my case above, just marrying up why the change occurred on this occasion!

[yashmehrotra]

@jamesericdavidson I think we reached this state due to too many frequent iterations without considering the "why" for the changes

cc: @526avijitgupta

Do you have suggestions for the ideal way this can be approached ?

[jamesericdavidson]

@yashmehrotra FWIW, if we want to support the standard Hugo way, both _index.md and index-about.md can be permitted.

• Re-implement the _index.md check, and use it (if it exists)
• Replace index-about.md with _index.md in the docs, de-facto deprecating the use of index-about.md
• Check for both _index.md and index-about.md in the code (preferring _index.md if both files exist?)

Ergo, we avoid breakage for legacy users, support interoperability (i.e. the users ability to switch themes without file renaming or reconfiguration), and users who haven't updated Gokarna in a long time.

The only dubious condition is when both files exist - we just need to pick the least worst option, and openly document the behaviour.

I wouldn't suggest this approach if we hadn't already subjected users to one breaking change; I think breaking this file again isn't worth it, and would rather stick with index-about.md if supporting the standard Hugo way isn't valued.