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?
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.
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.
Related
I want to add a few config files to .github folder but I can't seem to find it in my repository. I do see the .git and .gitignore files. Where can I find this .github folder, Is it added by git or should I create it?
There isn't one unless you create it (and if you do, you should create it in the root directory for the repository).
Github repo I'm referencing: https://github.com/Dallas-Marshall/PersonalProjects/tree/master/discord_bot
I have a Personal Projects Repository on Github and have a README.md file in the root folder explaining the repo. However, the issue I am having is that inside a directory of the repo I have created another README.md file to explain that specific project but Github is not displaying it.
I have ensured the file is named correctly, is up to date on Github and have scanned settings to try and find an option to display it to no avail as yet.
Does anyone know how to get this file to display when viewing the directory that I have linked above.
Many Thanks,
Dallas Marshall
Your readme in the linked repo folder is empty. GitHub will start displaying it once it got content in it.
I am struggling to figure out why the only thing I see on github page is the read me file.
I followed the instructions to publish to a github page here :
https://abhiverma04.github.io/dummycv/
my repo
https://github.com/abhiverma04/dummycv
Looks like readme.md takes priority over index.html.
You can either make orphan gh-page branch and put all your files (except readme.md) to this branch. Or create /docs folder and copy all your files to the /docs folder except of readme.md. And after this action enable the relevant sourcesetting in GitHub pages as it is described in the GitHub documentation
Is there a way to tell github that the project's readme file is not README.md but <project-name>.md?
The GitHub documentation states that GitHub will specifically display the contents of a file named README.md that is present in the root of your project or in the .github or docs subdirectories.
There doesn't appear to be an alternative here, though you could make your README.md file simply contain a link to another page of your choice.
Create a directory called .github and add a README.md there, but not an ordinary file. Use a symlink to the file you want to be the readme.
$ mkdir .github
$ cd .github
$ ln -s ../project-name.md ./README.md
$ git add README.md
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?
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.