Markup: 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

[davejamesmiller]

+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 [email protected] 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.

[davejamesmiller]

@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 [email protected] 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

[RobertDober]

completely agree with odalet, but that made me think...
maybe all that should be done is to make the READ MORE link not to point to the #readme anymore but to README.md,
Would that not solve the problem?

Cheers

[unhashable]

+1 - no go?

[ralphschindler]

Can we get some kind of feature to alleviate this pain? Even if its a repository setting, a callback script, or something we can set somewhere that will allow us to rewrite certain links depending on the branch that README/doc is in? Something, anything, throw us a bone here, please!

-@ralphschindler

[psi-4ward]

+1

[aschempp]

+1
especially also important for relative image links!!

[monobasic]

+1

[danmunn]

+1

[0xced]

+1

[robertwahler]

+1

relative links should work seamlessly, that would allow generated docs to use the same links as github

[lorrin]

I would appreciate working relative links too, though I agree a GitHub based feature outside of the library might make the most sense.

[est]

github should just put wiki under the project directory like Google Code. Then you can link what you want.

[jaspermdegroot]

+1

Thanks for the new feature "Contributing Guidelines"!

However, when trying to link from the README.md to the new CONTRIBUTING.md I ran into this relative link issue. Would be great if this could be fixed :) Thanks!

[colszowka]

I agree with my predecessors that this is a major pain point for writing decent docs that do not end up being a 1000-line README.md.

Another use case @davejamesmiller already touched as well: When in my repo I have /docs/**/*.md and want to link against those from each other, I have to pass in a full Github url. This has two major drawbacks:

1. When I generate API docs for (in my case) ruby projects using yard, the supplementary docs will not be linked properly. This leads to invalid linking on services like http://rubydoc.info as well as locally generated documentation, forcing developers to either hardcode links to github even for local docs, or breaking relative links on Github
2. When using hardcoded links to the github rendering of the projects, the documentation is always coming from the branch linked against. This leads to many problems when browsing older docs, either on github or in local/online API docs: The links will point users to documentation that does not apply to the version of the library they are using. Say the rails project was using this documentation strategy: If they linked to docs/ActiveRecordBasics.md as a hard-coded link to github/master and a user still stuck on 2.3 would browse the API docs for his version, either on the Github branch or locally or wherever, clicking such a link will kick him to the latest version that applies to the soon-to-come 4.0 release, and even more so probably without realizing this. A real-world example of this problem is the Resque library: The documentation of the 2-year-old version 1.8.0 points developers to the most up-to-date version of docs/HOOKS.md instead of the one on the 1.18.0 tag

If you guys found a way to fix this, documentation for any given point in time would remain consistent when browsing the docs on github as well as anywhere else, and that would be greatly appreciated!

[ralphschindler]

bump. Please give us a feature that will alleviate this pain.

[b-long]

+1

[guiprav]

+1
Using absolute URL's is definitely not a solution because it doesn't support branches / tags (URL's would always point to master, right?). Also, like @davejamesmiller and even @technoweenie mentioned, Markdown files are not viewed only in GitHub, so relative paths are important and again absolute URL's are not the solution.

Not to be a dick, but I'd say this is not an enhancement, but a bug really.

[six8]

+1

The whole problem arises because in a path like https://github.com/user/project/tree/master "master" is treated as a filename, not a directory. If a trailing slash was enforced (ex: `https://github.com/user/project/tree/master/) as is the standard then relative URLs would work perfectly.

[pwolanin]

Indeed - adding that trailing slash to the URL fixes it - but that seems like a github infra issue, not related to this library?

[six8]

It is a github infrastructure issue but also an issue for anyone else setting up a simular infrastructure.

[dfernandez79]

@technoweenie Based on your comments, note that having only absolute paths makes reading the file everywhere worst, for example you cannot follow links locally, and the absolute links will point to a specific version.

I don't know the implications of the solution, but even when I don't know the github UI code internals, a solution based in JavaScript is not ugly as you describe it:

• The change will be only in one place the README presentation logic, it doesn't affect the markup parsing.
• In the browser is very easy to search for all a/img tags inside the README container, check if the href is relative and make it absolute based on the current branch

Maybe this kind of solution doesn't cover all the possible use cases, and maybe the reason to close it is because the functionality clashes a little bit with the Wiki stuff. But a lot of users like me wants it... please listen to your users, and consider to reopen it.

Maybe you can find an alternative solution that covers the user goals, in my case that is to have a starting point for the documentation that goes with the source code. The wiki doesn't work for me, because I want to keep the Markdown files inside a docs folder of the source tree, and since the first thing that the devs see in GitHub is the README its the ideal place to place documentation pointers.

[elijh]

+1

[danfuzz]

+1

Thanks in advance for your re-consideration!

[Mikolaj]

+1

[joeyespo]

+1

[mnapoli]

+1

[cloderic]

+1 to everyone else, would really help !

[clakech]

+1

For you information, if you watch a readme.md using this kind of url (https://github.com/github/markup/) with a slash at the end instead of (https://github.com/github/markup) without slash at then end... then relative link works!

[nfrancois]

+1

[ardumont]

+1

[jbmonville]

+1

[denlab]

+1

[LucHenninot]

+1

[massyl]

+1

[bergerjac]

technoweenie: One solution works great: use absolute URLs.

@technoweenie The keyword that I've always heard with git is distributed. Using absolute URLs seems to go against the idea of distributed and more towards centralized.

[ardumont]

@technoweenie you do not follow the git branches with absolute url too.

On Fri, Dec 7, 2012 at 8:35 PM, Jacob Berger [email protected]:

technoweenie: One solution works great: use absolute URLs.

@technoweenie https://github.com/technoweenie The keyword that I've
always heard with git is _distributed_. Using absolute URLs seems to go
against the idea of distributed and more towards centralized.

—
Reply to this email directly or view it on GitHubhttps://github.com/github/markup/issues/84#issuecomment-11143137.

[joeyespo]

I was looking around the code in this repo recently. I think @technoweenie and others are right, there's not much this code can do to help. This library merely forwards the 'render' calls to the respective libraries. And in Markdown, for example, the relative URLs are just translated directly to <a> or <img> elements.

I'm really looking forward to a fix, but it'll either be a fix in internal GitHub code, or by adding a post-processor here that resolve _all_ relative URLs in <a> and <img> elements to absolute ones, happening after the call to render. The post-processor would take an absolute URL like the one used in <base> a while back.

[bergerjac]

@joeyespo I dug into the code as well and your findings are correct.

This is a great issue, just in the wrong place.

[ralphschindler]

@bergerjac well, I am unsure there is a place where this issue can be filed against private github code, so this is the only place we can have a public discussion on the matter. Does GH have an issue tracker for things like this?

[guiprav]

Agreed, @ralphschindler. +1

If this isn't the right place, don't just pretend there isn't a problem. Move the issue to the right place instead.

[avodonosov]

+1

And I wish it work not only for markdown, but for other markup formats supported by github, like .org

[parkghost]

+1

[csabapalfi]

+1

[dhladky]

+1

[avodonosov]

This issue is closed, but there is a opened duplicate - #101

Makes sense to post your +1's there.

[mynameistechno]

+1

[mcantrell]

+1

[colszowka]

w00t! https://github.com/blog/1395-relative-links-in-markup-files

[doapp-ryanp]

awesome, thanks for all the push on this guys and to github for implementing.

[ralphschindler]

Great! Thanks to all involved!
-ralph

[dhladky]

Hmmm, if I understand the blog well, one needs to keep the names of md files unique. That is far from optimal. If you had serveral readme.md files in each directory, you still can not link them.

[colszowka]

@dhladky How exactly do you intend to have multiple files of the same name in the same directory on your filesystem?

[dhladky]

I was not precise. Imagine a directory tree, where each folder has one readme.md file. It is entirely possible. However the way you can create the relative link according to the blog is just the "readme.md" (no path). Which of the files do you refer if you do so? The way described in the blog means you have to have the file names to be unique no matter where in the directory tree they are. If you have a large project and you have some naming convention you are done.

[colszowka]

I see. Actually I think the blog post example is somewhat badly picked as it only refers to items at the root level. Something like [other readme](docs/foo/bar/baz/README.md) should work as expected relative to the current branch root, so in this case it should link to the path docs/foo/bar/baz/README.md

[dhladky]

What I understand in the blog, if you had docs/foo/bar/baz/README.md you need to change it to just README.md. I will investigate how it works. If docs/foo/bar/baz/README.md worked and the link was calculated to match the proper branch, it would be brilliant.

[colszowka]

From what I reckon that was the purpose of this whole excercise :)

[dhladky]

It was and that is why I was disappointed after reading the blog. :)

[brauliobo]

+1 to variables support (branch, etc)

[muescha]

+1

it should use relative links in issues/pullrequests/comments in pull requests

Example:

where

i write something in a comment of a pull request

what

i would like to write [options](website/documentation/options.md#default-ui-options)

current

it matches to:

https://github.com/dimsemenov/PhotoSwipe/pull/905/website/documentation/options.md#default-ui-options

expected

it should be matched to this:

https://github.com/dimsemenov/PhotoSwipe/blob/master/website/documentation/options.md#default-ui-options

[avodonosov]

@timofonic news about what? This feature is implemented long ago.

[muescha]

@avodonosov in pull requests its still not implemented

[avodonosov]

@muescha @tiabobia ah, pull requests. Probably discussing it in a closed issue might be inefficient. Also, have you seen https://github.com/github/markup/issues/285 ?

[muescha]

@avodonosov ok i will open a new issue for this

here is the number: #576

[OmgImAlexis]

Did this ever get fixed/implemented?

[AxelStrem]

+1 to variables support (username/repo) as CI build plaques/links are a source of pain in forked repos

[sc0ttkclark]

This idea lives again in #913!

[lorddev]

This was reported as fixed in 2013 but it appears to be broken again.

[rzr]

It seems it has been fixed no?

I came to this from:
https://stackoverflow.com/questions/7653483/github-relative-link-in-markdown-file

[mamadOuologuem]

+1

[rynop]

@mamadOuologuem does your +1 mean it is broken again? If YES, do you have URL where it's exhibiting broken behaivor AND I think you should open a new issue to get it some visibility.