Specify alternate project-level README.md on GitHub

Using GitHub's web-based interface I cannot figure out how to specify an alternate path / filename for the project's README file.

When creating a new README, the web interface does give me the option of using any arbitrary path or filename I want, but the file I select is not used as the project-level README. I would like it to be displayed when users visit the project page.

In the context of projects that are modules or extensions (e.g. Magento 1 modules) having all such README files at /README.md for all such projects would make them all get over-written in the final merge, so an alternate path or filename should be used (e.g. /docs/projectname/README.md or /projectname.md).

How can I do this in a way that specifies that file as the default README?

Solution

GitHub looks for README files in a few places:

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.

If you want to use another file for your project-level README I suggest creating a hidden .github/ directory and symlinking your file there with a name GitHub expects.

On Linux or macOS this should be fairly straightforward:

  # From your repository root
  mkdir .github
  cd .github
  ln -s ../docs/projectname/some-README.md README.md

On Windows things are a bit trickier.

Symbolic links are only available on NTFS filesystems on Windows Vista or later, and creating them requires special rights or Developer Mode. They are not supported by Git on Windows out of the box.

In your Git shell, in the root directory of your repository, enable symlinks for the current repo:
```
  git config core.symlinks true
```
Now run cmd.exe as administrator¹ and cd to the repository root. Make your symlink:
```
  mkdir .github
  cd .github
  mklink README.md ..\docs\projectname\some-README.md
```
Note that the name of the link goes before the name of the real file here, in contrast with the Linux and macOS instructions above. You can close cmd.exe now and go back to Git Bash.

Now commit .github/README.md and push to GitHub. You'll probably want to make sure that there isn't a real README file in any of the other locations GitHub uses (the repository root or a docs/ folder in the repository root).

Windows users who clone the repository won't get a symlink automatically. If they wish to have that behaviour they should clone with a special argument:

git clone -c core.symlinks=true <repo-url>

¹It's possible to grant mklink permissions to non-admin users, but running as administrator is likely the simplest solution.