How do I make another file the standard instead of README.md

[fjgenieter]

I'm new to GitHub and wondering how I make another file automatically show that is not called README.md.

Thank you in advance!

[VerzatileDev]

Ahh so index.md is another one. Can I make a file with a completely different name?

I can't quite work out from the link what to write in the .gitattributes file. Say I have a text file my_readme.md, what would I write into .gitattributes to make github display it?

Now what about if I have files called my_readme.md in all the subfolders of my repo, would it still work?

As best of my knowledge it should be that you access the default and then add a renamed version behind it.

README.md MyREADME.md

[zmajeed]

I looked at Github's doc on README - https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes - all I can say is it doesn't show how to have a README file that is not named README - the doc mentions using markdown to edit READMEs - but it doesn't say what formats are actually supported for README - it does list some locations a README can live besides the top of the repo

I also found github/markup#360 that provides some clarity on how Github selects the README file to display

In short - it seems the README filename must be README with supported extensions like .md, .rst, .txt and others - the filename seems case-insensitive as seen in many repos - the file can be in a few supported locations other than the top of the repo

I don't see anything relevant or helpful in docs on the gitarributes file - it was a complete waste of time

I found suggestions like creating a README symlink to a different file in the repo - but I didn't bother to try any of these workarounds

[mikenakis]

[how to] make another file automatically show that is not called README.md [?]

You can't. GitHub does not support that.

GitHub has decided that "README.md should be good enough for everyone."

GitHub could easily offer a setting for specifying which file to consider as the README file, but it does not offer such a setting.

Here is a partial workaround, which may and may not work for you, depending on what you are ultimately trying to accomplish:

1. Rename your README.md to my_README.md
2. Create a symbolic link called README.md which points to my_README.md

A symbolic link (a.k.a. symlink) can be created:

• in Linux: using the ln command.
• in Windows: using the mklink command.

Note: it is important to specify the target of the symbolic link as my_README.md or ./relative/path/to/my_README.md so that the link is relative, not absolute.

GitHub recognizes symbolic links and shows them with slightly different icons that have a little overlaid arrow.

On the landing page of your repository, GitHub understands that README.md is a symbolic link, and shows the contents of the file pointed by the symbolic link instead.