Repository navigation
Symbolic links and other methods of indicating the README format #21
Description
This may be in the wrong issue queue; if so, I apologize in advance, and humbly request to be redirected to the proper facility.
I've discovered to my chagrin that README* files which are symlinks do not get recognized by github, or at least they are not being displayed as the README file for the branch page.
This would be quite useful, since I usually write my documentation in markdown, but for some projects, e.g. Python modules, it's important to have a README file with a name other than README.markdown. Since markdown is text, ln -s README.txt README.markdown && git add README.markdown would work quite well, except that the github web system doesn't seem to follow symlinks.
I guess I could rebuild (i.e. copy) the README.txt file in a commit/merge hook, but it's sort of a hassle to have to write a commit hook to do this, and it's somewhat confusing for people to have two files in their cloned repo or download which are exactly the same. It's also in violation, I'm sure, of some fundamental rule of source control management theory, the one about not committing generated files.
This issue is related to issue #3, in that if that feature were implemented in a way that allowed for reliable detection of markdown within *.txt files it wouldn't be necessary. It's not really clear that that's possible, though, and assuming that somebody is writing markdown when they just want their file displayed as plain text would be an annoying way to do things.
That issue is also related because somebody mentioned this approach in a comment on the issue.
There was also a suggestion made to allow the repo maintainer to indicate what format the README should be parsed as; this was responded to to the effect that such a feature was unlikely to be put into place because it "gains nothing over just adding the correct extension." Hopefully my above statements serve as a sensible objection to this assertion.
Another option, not mentioned in the comments thread for that issue, could be to use a metadata file in the repo to save github-related options, e.g. /.github:
[README]
file = README.txt
format = markdown
I leave it to your graces to make a wise ruling on this matter.
Activity
kneath commentedon Sep 20, 2010
That's a lot of text.
Your second paragraph is fine, I'll see what we can do to support traversing symlinks as well for readme name matching.
intuited commentedon Sep 20, 2010
Awesome, cheers. I figure it's better to say it up front than to write a bunch of disorganized comments after :)
kneath commentedon Sep 23, 2010
Shipped this yesterday.
intuited commentedon Sep 23, 2010
Sweet, thanks a bunch.
ravn commentedon May 10, 2018
I just tested having "/Main.md" being a symbolic link to "/src/main/java/demo/Main.java" which is a valid markdown file (this is sort of the whole point of this test as I am looking for a way to document Java code better than javadoc) and it is just rendered as a box with the symbolic link target name. Have I misunderstood how this is to be done?
pepasflo commentedon Nov 1, 2018
It appears this isn't working anymore 🙁~UPDATE: hmm, actually it looks like this is working for merged files: ~
https://github.com/pepasflo/do-symlinked-readmes-work/blob/master/docs/controllers.mdhttps://github.com/pepasflo/do-symlinked-readmes-work/tree/master/src/controllersHowever, it appears this isn't working when you browse the files of a PR which hasn't been merged yet.UPDATE2: Hmm, so it is working correctly in this PR:
So why is this not working in a PR in our private repo?
Here's what I see:
frozenfrank commentedon Feb 28, 2025
@ravn I believe this feature only affects the rendering of the repo
README.mdfile on the repo landing page and similar places. This feature, unfortunately, does not render all symlinks throughout the filesystem.See my example.
On this repo, the welcome page follows the symlink to display the markdown content stored in PHASE7_PERF_TESTING.md; however, actually visiting the README.md file just shows the text of the file reference 😦
docs(fn-47): repo docs decomposition — promote root README + flat doc…