Github Pages: /README.md relative links to other foo/README.md files but breaks if foo/index.html exists

Question

My repo, which is also a github-page, has its main README.md with multiple links to README.md's in sub-dirs in the repo:

[models](./models/README.md)

The ghpage works nicely. It converts the markdown to html.

But it does not work for dirs that also have an index.html file, It then simply shows the markdown text. not its html.

And if I rename the index.html file, the problem goes away!

My question is: What is causing this? Maybe a Jekyll issue? Config file setting? How can I have relative links to.md files work even when an index.html file is present?

Thanks!

Answer 1

Found the answer here: https://github.community/t/linking-files-into-folders/115936/2

Specifically, if an index.html and README.md are in the same repo, the index.html wins:

Your repository contains both a README.md file and an index.html file. This presents a conflict, as GitHub Pages is designed to publish both files as index.html. Under these circumstances, the index.html file in your repository takes precedence, and GitHub Pages skips the process of converting your README.md file to HTML.

This makes a lot of sense, but is not well documented, alas. Hope folks find it here.