Support branch relative links in README.md on root of repo

[doapp-ryanp]

Relative html anchor links work great from one .md file to another, however they do not work from the README.md if it is in the root of the repo. By default, github renders the README.md file in the webapp, and all relative links in there are relative to the URL (which does not include any branch name). It would be sweet if you added logic to this special case to create anchors so they included the current branch.

I have written up a detailed explanation of the problem and an example here:
http://stackoverflow.com/questions/7653483/github-relative-link-in-markdown-file

[ralphschindler]

I would like this as well so I can write documentation that references the code.

[mloskot]

I've been just looking for similar feature, trying to use SHA or branch or repo links in my README.md.
It would be a sweet feature.

[cbeams]

+1. relative links from a concise readme.md file to, let's say, a more detailed building-from-source.md allows for keeping such documentation in sync with the code instead of relying on the wiki.

[technoweenie]

We tried adding a <base> tag for this, but it causes problems with other relative links on the site.

[ralphschindler]

@technoweenie any other comments? This was a feature request / not a bug. Github already sports its own "Github Flavored Markdown", and since github has special relative paths - it makes sense to make these work in the github sense.

http://github.github.com/github-flavored-markdown/

Or, are you saying, "No, we will not entertain this feature request"? And basically, we're only talking about the README.md here- which is also specific to github in that it displays the read me as the project index.

[bpierre]

Is there any chance you reopen this issue?

Why not rewrite the relative URLs in .md files with the absolute ones (only for the HTML rendering)?

[doapp-ryanp]

There are also some other creative options. Could use iframe for the preview of the .md, and relative links would work. You could also potentially leverage the HTML base tag ( http://www.w3schools.com/tags/tag_base.asp ). Could write some JS code that identifies links in the .md preview and alters based on the current/default branch.

[pulkitsinghal]

@technoweenie Can't you please try again? There is always some solution. This request is a very important one because without it, the whole process of "pull requests" gets really messy when it comes to documentation. URLs for snapshots etc. have to be rewritten and there is no way to do a clean merge out of the pull request. Please reconsider & try a different approach.

[dblock]

+1, this is super painful for open-sourcing wiki-like content

[d13r]

+1

[technoweenie]

The problem is readmes can be viewed on multiple URLs. Every solution requires a pile of hacks:

• Keep multiple caches of the rendered readme to work on every page it's displayed.
• iframe/javascript whammy jammy.

One solution works great: use absolute URLs. Don't assume your README will always be read on GitHub.

Hit up support@github.com if you want to talk about GitHub issues. This is out of scope of this small OSS library.

[dblock]

@technoweenie I feel your pain, but maybe you could fix the 75% scenario?

Each markdown file is truly located in one place, the real URL is something like https://github.com/dblock/mongoid-cached-json/blob/master/README.md - so why not add a substitution like link - every ./ would be replaced by the real location of the file?

Sorry if I keep discussing the issue here, already hit support. Wil stop now.

[d13r]

@technoweenie

Don't assume your README will always be read on GitHub.

That's exactly what I'd like to avoid - hard-coding absolute links to the GitHub website instead of using relative ones to link to files in the same directory. That way if you're reading it outside GitHub you get a link to the local copy of the file.

I'll email that same thing to support@github.com as you said.

Cheers

[odalet]

+1
It's all the more a hassle as relative links work when clicked from an explicitly opened readme.md