README.md unpredictably sometimes takes priority over index.md

[sdaitzman]

• I confirm that this is an issue rather than a question.

Bug report

Steps to reproduce

1. Create index.md in project root // site builds from index.md
2. Create README.md in project root // site still builds from index.md locally and on my Netlify deploy
3. Continue working // site sometimes builds from README.md now, and sometimes builds from index.md

What is expected?

If index.md exists, it should take priority over README.md

What is actually happening?

README.md sometimes gets built. index.md sometimes gets built.

Other relevant information

• Output of npx vuepress info in my VuePress project:

Environment Info:

  System:
    OS: macOS 10.15.2
    CPU: (16) x64 Intel(R) Core(TM) i9-9880H CPU @ 2.30GHz
  Binaries:
    Node: 10.7.0 - /usr/local/bin/node
    Yarn: 1.21.1 - /usr/local/bin/yarn
    npm: 6.13.4 - /usr/local/bin/npm
  Browsers:
    Chrome: 78.0.3904.97
    Firefox: 71.0
    Safari: 13.0.4
  npmPackages:
    @vuepress/core:  1.2.0
    @vuepress/theme-default:  1.2.0
    vuepress: ^1.2.0 => 1.2.0
  npmGlobalPackages:
    vuepress: Not Found

[haoranpb]

Hi @sdaitzman , currently both README.md and index.md will be built into index.html, so I think you should try to avoid putting both of them in the same location. I didn't try your scenario a lot, but in my case, index.md never get build.

If you want to use the README.md simply to describe your project and don't want vuepress to build it. You can try to use patterns to specify that you don't want README.md files to be resolved.

I recall an issue talking about whether allowing README.md and index.md both be built into index.html is a good idea, but I can't seem to find it.

[sdaitzman]

@ludanxer thank you, that sounds reasonable! I'll work around this.

[sdaitzman]

Here's an example of how this can work: sdaitzman/Olin-PIT-site@75ed3d0#diff-1d7df657215ba8fd3a42fe5342bc3ee6R21

[sdaitzman]

Update: another, even easier solution is just to rename your readme.md to readme.markdown, which GitHub etc. will still recognize (but will not get built by VuePress). ✨

[ddazal]

Hi guys,

I know that we shouldn't place a README.md file and a index.md file in the same folder but, playing around, I get the content of the index.md file on build. Do you think the priority or lookup order should appear somewhere in the docs?

[sdaitzman]

@ddazal I actually think that it's pretty reasonable for the root to contain a README.md file, intended for information about the documentation/website/blog and how to build it, and an index.md file, intended for specifying the actual contents of the homepage.

The pattern I've observed is that the index.md file will take priority, but only sometimes. This makes me think there's a race condition somewhere, or some unpredictable filesystem behavior.

Regardless of best practices, I definitely agree that a predictable behavior should exist and be described by the docs.