Configure github to use some other file as README

Question

Because of how Eclipse and EGit organize files and directories, I have my README.md file not in the root directory of my git repository but one folder deeper. How can I tell github to show some_folder/README.md as project's readme?

Answer 1

• In the root directory of your repo, create a folder named .github.
• Create a file named README.md in this folder.
• Save the relative path of the file you want to use as the repo README in .github/README.md.

This causes README.md to be interpreted as a symbolic link (symlink) file.

Example:

• This repo has files named README.md and cmod-readme.md in its root directory. Normally the former would be used as the README shown on the repo's main page, but instead the latter is used.
• The repo contains a .github/README.md file, which contains the relative path to cmod-readme.md, i.e., ../cmod-readme.md.

The fact that GitHub will follow symlinks when locating a repo's README doesn't seem to be documented, although the .github folder is mentioned on this page in GitHub's docs:

If you put your README file in your repository's root, docs, or hidden .github directory, GitHub will recognize and automatically surface your README to repository visitors.

It's also interesting that (based on the example repo linked above) GitHub apparently prioritizes the README.md file in .github over a file of the same name in the respository's root.

Answer 2

This seemed to do it for me:

https://stackoverflow.com/a/49981731/7452130

Github wouldn't interpret my .github/README.md file as a symlink unless I created a symlink on my system and then pushed it.