Use alternative tree root instead of index.md (such as README.md)

[robcresswell]

It'd be great to be able to configure the root file that hugo assumes when building its front matter, when creating documentation sites, for the following reasons:

• GitHub / GitLab naturally render README.md files in each directory when browsing source code online.
• Many modern web frameworks, especially in JS ecosystems, have adopted component-based code bases, where each component contains its own documentation, tests, and implementation. This may look something like:

$ tree src/components/table
src/components/table
├── README.md
├── index.js
├── table.vue
└── test.js

This seems to me to be extremely well aligned with Hugo's tree structure for organisation, other than the hardcoded index filename requirement.

I think this is useful because it helps developers consume documentation in this manner how ever they'd like; either reading directly from github, or in a more professional generated output from Hugo.

[bep]

I see your point, but it looks like an expensive feature. If we look beyond the hardcodings, I don't see a way to do this without either 1) add some kind of config option or 2) break stuff. 1) is doable, of course, but that would kind if limit the "content portability" that the issue is trying to improve in the first place.

Once people get used to these "index.md" files etc., having people share articles (as bundles possibly) in zip files and just add it to the content and it just works ...

As a contributor to some magazine I would love to not have to do: "Hey, editor, here is my article. Oh, I have used a non-standard naming scheme, so you must toggle some setting and have Hugo version at least ..."

[robcresswell]

I see your point, and 1) is the route I would suggest. Also with regards to it not being a standard for Hugo, it is a "sort of standard" for many source control sites, which is why it would be great to be able to take advantage of that.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. The resources of the Hugo team are limited, and so we are asking for your help. If this is a bug and you can still reproduce this error on the master branch, please reply with all of the information you have about it in order to keep the issue open. If this is a feature request, and you feel that it is still relevant and valuable, please tell us why. This issue will automatically be closed in the near future if no further activity occurs. Thank you for all your contributions.

[evankanderson]

Hey, this is of interest to me, and looks like it may be less of a challenge than it was in 2018 (at least based on a fairly quick glance through the code for _index).

Is this still of interest/would a PR be accepted?

[evankanderson]

Looking at this further, it looks like a matter of plumbing the configuration into https://github.com/gohugoio/hugo/blob/master/hugofs/files/classifier.go#L84 and a few other places.

My initial thought was to make this a build option, but that means that we may need to open bundle files during the filesystem traversal to read front matter.

@bep , do you have a preference on implementation here (global option, or build option)?

[bep]

So, my recent work in this area has been slowly making this more friendly for "non file pages" (aka pages from data).

I would love to add this if it didn't in some way make that thing harder.

The grand idea now is that if you leave out taxonomies there are

• sections (aka branch bundles) and bundles (aka leaf bundles).
• So with multiple data sources (we have that today with the mounts and theme components, but it will be even more interesting once we read pages from JSON files and WorPress and such), a given resource (let's say an image) will be mapped and potentially merged into one of the above (section or bundle) or just copied as-is. Page "files" (md-files etc.) will either become section content, bundle content or a bundle resource.

I'm not sure how I will handle WordPress etc. yet, but if we for the sake of this discussion say that:

• README.md is a file source "thing"
• We can have a mix of mounts with _index.md and README.md (we have an overlay file system so these will be merged)

I would think that the only sane way to implement this would be at the file system level.

I admit that part of that code is a little hard to understand (the decorators, especially), but I think the gist of it is:

• A README.md file should look like it's named _index.md in all situations where this matters (esp. the merge)

[evankanderson]

That's roughly what I've got in progress; there are a few ugly bits because I got started on the build option choice, so each directory in the "fs" would have a list of file prefixes (e.g. "README" or whatnot) that would be handled the same as _index or index, with the first existing file taking precedence, and merging the build options up the sections hierarchy.

[bep]

Sorry for the delay, I have created this proposal that should handle this case: #10129