Vuepress: Rename "README.md" files to "index.md"

[ghost]

Feature request

README.md is too specific for generic root content files and can be misleading. #23 allows to use index.md.

What problem does this feature solve?

README is the established name for contextual documentation files. Using this name can be misleading for newcomers and index.md makes it easier to understand what the purpose of the file is.

I understand that everyone is free to use either README or index but note that many people will follow your example here, check out how it's done in your docs and at least for me it was not obvious while reading the documentation that README files are treated as index files or that the naming is meaningful at all.

https://github.com/vuejs/vuepress/blob/master/packages/%40vuepress/theme-default/components/Page.vue#L127 probably needs to be changed, too.

[ulivz]

Both of them are supported, using index.md or README.md is up to you. See https://github.com/vuejs/vuepress/pull/23.

[ghost]

In this case it should be explained in the docs. You probably missed the edit I submitted just when you closed this.

[ghost]

Also, please check if

https://github.com/vuejs/vuepress/blob/master/packages/%40vuepress/theme-default/components/Page.vue#L127 probably needs to be changed, too.

If I understand it correctly, index.md breaks the edit links.

[ulivz]

Our original intention is that writing two solutions in the document at the same time may make the novice fear: which one should I choose?

If you feel that there is a suitable location in the document to declare this choice, welcome to contribute for that.

What you said later is really a problem, but it doesn't seem to be easily fixed. We have to pass the type info(index or README) from server side to client side, which is not very elegant.

[ulivz]

To avoid problems, it is recommended that you use the README for now. We can record this problem first (You can open another issue for that), and then confirm that if there is a suitable solution and then switch back.

[ghost]

Our original intention is that writing two programs in the document at the same time may make the novice fear: which solution should I choose?

My suggestion here is to use index.md as the only standard for root content files. README is as described not a good name and can cause conflicts in github environments. Replace README with index, then add a paragraph in the docs that explains the purpose and usage of index.md files. I'm willing to contribute to the docs once I've learned more about it, for now I can only help with reporting issues.

To avoid problems, it is recommended that you use the README for now.

Alright, good to know.

[viktorsmari]

This is a top hit on Google, but how do you use README.md as a 'normal readme' and not as a website?
I wanted to use the README.md as a guide how to set up the project (as it's normally done on GitHub and Gitlab).

On Github and Gitlab (and more?), the README.md is rendered on every repositories page.

So, I want to disable what VuePress does out of the box (converting a README.md to an index.html)
and simply use a index.md instead.

Is this easily possible? (And why on earth is it not the default behaviour!?)

[veidenberg]

This is a top hit on Google, but how do you use README.md as a 'normal readme' and not as a website?

Fortunatley the default filename selection is slightly different for VuePress and Github. To target markdown files for both, rename the GitHub readme as README.markdown and Vuepress file as index.md or readme.md.