Markup: Branch relative links in markdown files

[davekinkead]

A really annoying issue on github is the parsing of links in readme files. Not just for me but for lots of people (see https://github.com/github/markup/issues/84 http://stackoverflow.com/questions/7653483/github-relative-link-in-markdown-file)

For readme links to currently work, the absolute link including repo/blob/branch must be hardcoded. That works when viewing on git hub but not for local files. Alternatively, relative links work on local but not on github.

So, why can't github just add the 'repo/blob/branch' part to any relative urls in .md files when parsing? That way, when we want to point an absolute, we include the http://....., and when we want to link to other project files, it works both locally & on github. The whole git philosophy is about distributed control but the current link parsing goes against this

Example

[some text][link]
[link]:subdir/filename

when in a markdown file should be parsed to http://github.com/account/project/blob/branch/subdir/filename

[pulkitsinghal]

+1 this feature is badly needed

[ghost]

The only problem with this is that the documentation then does not fulfill the original intent of markdown. Markdown should be usable as plain text and renderable. If you use relative links then it loses it's appeal.

[pulkitsinghal]

That problem is already present, I don't think folks can see an absolute URL as an image, any better than they can see a relative URL.

[ghost]

Yes, but at least they can click on it to see it.

[pulkitsinghal]

Right, and I'm saying that if the URL is leading to a fork that might not be there any more, may have been created in order to get the merges into the original, then they can't see it, its broken.

[davekinkead]

As it currently stands, .md renders both relative and absolute hyperlinks. Within the same folder, "file.md" and "http://example.com/file.md" both render to the same file, and that's true where ever the .md file is.

But because of how github locates sub directories (it inserts the /blob/branch part when displaying a repo via http), relative path between resources differ depending on where the repo hosted. Its entirely a github thing and nothing to do with markup 'intent'.

To fix this, github need to change how they render markup to account for it, and they can do this by adding the /blob/fork part to any relative links.

[jumoel]

+1

When adding images to a repo and referencing them in a Markdown file, it's kind of ugly to add a absolute GitHub URL.
The markdown renders properly on a local checkout without absolute URL's. It should do the same on GitHub.

[orestes]

+1

I was banging my head against the wall thinking I was doing something wrong. I just assumed this should be github's expected behaviour.

[ruggeri]

+1!

[fabiokung]

:+1:

[ghost]

I guess it's time someone merged this PR....

[schinen]

+1

[zagen]

+1

[schleyfox]

+1

[ghost]

I think someone needs to submit a PR otherwise this ticket will go nowhere.

[waawal]

:+1:

[patcon]

@davekinkead :+1:

EDIT: Oh hey, just realized lots of +1's, but no pull requests...

[FichteFoll]

I looked into the source, but I don't know any Ruby and I don't really get the code.

[ghost]

So many +1's but no action.... time to unsub from the notifications...

[dain]

+1

[sindresorhus]

:+1:

[Aqua-Ye]

+1

[jansegre]

+1
I still think this should be considered a bug.
Suppose an .md is rendered within a directory, the produced .html will link relative to that dir, and if that dir is served statically then the relative link will work just fine.
As far as I can see this is an issue with rendering an .md serving it on a different file tree and not updating relative links.
Absolute urls are bad for two reasons, github may not be the only place where the repo is exposed and they are more not pleasant on plaintext meaning they are not relative (duh!).

[erikw]

+1

[Pym]

+1

[songz]

+1

[excavador]

+1

[jrochkind]

+1

if there were a way to do this, it would make managing documentation in sync with code so so so much easier, with github as the viewer.

[wiseman]

+1

[aronwoost]

+1

[sebdeckers]

+1

[petrkozorezov]

+1

[TylerBrock]

+1

[rkylberg]

+1

[katiekuwata]

+1

[mmichaelis]

+1

[andreasdurietz-tradedoubler]

+1

[Julian]

If (hopefully when!) this happens, it'd be nice if it worked for all supported readme formats certainly (specifically, reST too).

[joeyespo]

+1

A repo is not very portable when it's tied to an absolute Github URL. Sure, you could tie it to a mutual 3rd party source, but this is redundant and adds an unnecessary dependency when images such as logos and screenshots are already contained within the repo.

[mnapoli]

+1

[0xced]

Every single time I add a screenshot in my README.md file I get bitten by this. Please consider doing something about this problem.

[TylerBrock]

Yes. Please guys. This is what I want for Christmas.
On Nov 21, 2012 6:41 AM, "Cédric Luthi" [email protected] wrote:

Every single time I add a screenshot in my README.md file I get bitten by
this. Please consider doing something about this problem.

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

[regularlady]

+1

[mamalisk]

+1. Very important feature!

[Julian]

I realize that this comment will be slightly ironic, but can we please stop +1'ing the issue. It's fairly obvious (I hope) how important this should be and I do think that GitHub probably will fix it sooner or later. +1'ing the issue is just annoying, since it hits every watcher of the thread with a useless email.

In fact, now that I think about it, maybe it'd be nice to have a feature by which once a thread has > 20 comments, you can't post a new comment to it with the word +1 unless it were > n words.

[joeyespo]

@Julian It may be annoying but if it helps the issue get attention, it'd be worth it to me. And perhaps some others who added their own +1.

It's fairly obvious (I hope) how important this should be

This is why adding +1 is a good thing. "Hope" isn't enough to get an issue noticed. Without some indication of importance from the community, this will most likely continue to be perceived as a low-priority issue.

If anything, having a "star" feature for issues would probably lessen the noise better than disabling "+1" comments.

[Julian]

I really didn't want to launch an "are +1s " discussion to create even more noise, so if you just disagree we can leave it at that, but no I don't think they are in the least bit helping. As a developer I completely ignore +1s, and they add absolutely nothing. They don't make me at all more likely to fix the issue. If its important it gets fixed, if I the maintainer don't think it is, well you'd better convince me it is, not just spam the ticket.

And no, I don't think starring tickets would help much, just see Google Code, where such a thing exists and +1s are only a tad less prevalent.

[FichteFoll]

Someone (capable of Ruby) should get in contact with the developers/maintainers/whoever responsible and persuade them to add this feature, if not as a pull request or something. I searched for the relevant code a few months ago (as stated above) but there hasn't changed much since then. I still don't know any Ruby and I still don't know where the relevant code is in the first place.

[slant]

+1

[jrochkind]

Part of the issue is that this issue is on the "markdown" library that github uses, which is made available as open source, as an isolated component.

But I can't figure out any way to solve the actual use case only by touching this isolated 'markdown' library -- if I could, I'd submit a pull request, because I'd really like this feature, it would make writing and presenting really good documentation on github-hosted projects so much easier.

But I think an actual solution to the problem needs to involve code in github itself, not just in this isolated markdown library. Code that is not open source, and we can not see or submit pull requests for (so far as I know?), we just have to rely on the kindness/interest of github.

The nature of the problem is that a relative URL in a README will point to _different_ places when viewed from github project home (displaying the README at the bottom of the page, but you've got github.com/somebody/something in your browser location bar), vs looking directly at the README file itself (and then it may be different if you are looking at master, at a tag, at a branch HEAD, or at a specific commit sha). (And this all applies to README's at subdirs too not just project root). The only solution I can think of is to render several different versions of a README, manually filtering/altering relative URLs differently in some of them). Which probably has some gotchas I'm not thinking of too, and is probably harder than it seems at first -- but would need to happen in github's code, not in this 'markdown' sub-project, and the actual gotchas and problems (or other ideas for solutions) are really only going to become apparent to someone with access to that code who experiments.

Nobody will probably see this comment in the flood of +1's, but there it is.

[darvin]

+1

[avodonosov]

+1

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

@davekinkead, could you rename the issue? not markdown files, but any markup files. I.e. the fix should url-rewrite relative links in the generated HTML, not when parsing markdown.

[Kyso]

Yeah, this definitely needs fixing.

[flyingmutant]

+1

[avodonosov]

I wonder, if this is the most wanted feature request.

[pwolanin]

Read the comments on #84. This is NOT a ruby issue, but a github infra issue - they need to link/redirect to repo paths using a trailing slash:

"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."

[TylerBrock]

Still, this is the only forum we really have to complain about it... so,
here we are.

On Fri, Jan 4, 2013 at 12:10 PM, pwolanin [email protected] wrote:

Read the comments on #84 https://github.com/github/markup/issues/84.
This is NOT a ruby issue, but a github infra issue - they need to
link/redirect to repo paths using a trailing slash:

"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."

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

[jansegre]

This should be simple enough to fix for all markup languages not only markdown.
A post render filter which replace relative links with absolutes sensitive to the context which the html is loaded would suffice.

That is, if a project github.com/user/project has a README.md with a link to COPYING.md, after the html is rendered the link <a href="COPYING.md">foo</a> when viewed from github.com/user/project would be replaced by <a href="/user/project/blob/master/COPYING.md" class="js-slide-to">foo</a> if COPYING.md hits a file from where README.md is, if it hits a dir then <a href="/user/project/tree/master/COPYING.md" class="js-slide-to">foo</a>. But even only initially allowing links to file and not to dirs would cover most cases.
That doesn't seems to be hard at all. If I was familiar with any ruby html parser I'd write a draft of this code, it should receive the rendered html and a context, and output an html with links fixed. To cover the file/dir blob/tree thing it'd need access to the repo tree, but that's an extra.

[avodonosov]

@jansegre how about the redirection solution @pwolanin posted two comments above yours? It is simpler and should work, do you see any flaws in it?

[jrochkind]

I doubt github wants to apply a dynamic 'post render filter' to every
README or other markdown displayed, as opposed to simply serving
static pre-rendered files. Non-trivial computational cost there at the
scale of github. Alternately, I suppose they could render multiple
versions of the page for every possible URL context it could be
displayed in, but that becomes a maintainability problem too (since
every tag or branch is another context).

Anyway, it's kind of pointless for us to guess at what solutions would
be best or feasible for github, without knowing their internal
architecture or constraints. What you or I think is 'simple' probably
isn't, we're just guessing. But if someone at github saw this as an
issue worth spending time on, I suspect they could find some
reasonable solution (I would also be surprised if it were Jan's). It
seems they do not. They seem to be mostly be focusing on features
which add value to the paid accounts, and perhaps good in-repo
documentation isn't important to internal projects, I dunno. I wish
they did something here, but it's really in github's court, and is not
something that can be solved in this open source codebase we are
commenting on, it can only be solved in github's internal codebase.

[TylerBrock]

What about just using client side JS to append the current domain and
relative path? That would cost nothing and do the trick.

On Fri, Jan 4, 2013 at 1:41 PM, Jonathan Rochkind
[email protected]:

I doubt github wants to apply a dynamic 'post render filter' to every
README or other markdown displayed, as opposed to simply serving
static pre-rendered files. Non-trivial computational cost there at the
scale of github. Alternately, I suppose they could render multiple
versions of the page for every possible URL context it could be
displayed in, but that becomes a maintainability problem too (since
every tag or branch is another context).

Anyway, it's kind of pointless for us to guess at what solutions would
be best or feasible for github, without knowing their internal
architecture or constraints. What you or I think is 'simple' probably
isn't, we're just guessing. But if someone at github saw this as an
issue worth spending time on, I suspect they could find some
reasonable solution (I would also be surprised if it were Jan's). It
seems they do not. They seem to be mostly be focusing on features
which add value to the paid accounts, and perhaps good in-repo
documentation isn't important to internal projects, I dunno. I wish
they did something here, but it's really in github's court, and is not
something that can be solved in this open source codebase we are
commenting on, it can only be solved in github's internal codebase.

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

[jansegre]

@avodonosov that solution doesn't cover the main README.md which displays by default on the project main page.

@jrochkind that would be a matter of caching the post-rendered html or caching the post parsed html and leaving appropriate places for replacing as a template, processing templates is already done anyway.

@TylerBrock yeah, that is in fact so simpler to do with jquery that it deserves a userside js for a working proof.

[jansegre]

I've made an initial version that covers the simplest case.
Contributions are accepted.
This may became a chrome/firefox extension.

https://github.com/jansegre/ghrelativelinkfix-js/blob/master/fix.js

If the js is run on this page https://github.com/jansegre/ghrelativelinkfix-js the link to see the link to COPYING.md work.

[avodonosov]

@jansegre Ah, yes, right, main README.md on the main page (I actually considered these two approaches and also came to conclusion about url-rewriting; but forgot why the redirect approach would not work).

So, README.md may be viewed from at different URLs:
https://github.com/user/project
https://github.com/user/project/
https://github.com/user/project/blob/master/README.md
https://github.com/user/project/blob/other-branch/README.md

In the fist 3 cases rewriting of COPYING.md URL will always be the same:
<a href="/user/project/blob/master/COPYING.md" class="js-slide-to">foo</a>
But in the last case it should be
<a href="/user/project/blob/other-branch/COPYING.md" class="js-slide-to">foo</a>

I've made an initial version that covers the simplest case.
Contributions are accepted.

Great, I hope to try it soon

This may became a chrome/firefox extension.

Or used with Spidermonkey. But of course only during the proof of concept phase, because I wish this solution to work not for me personally, but for other people who visit my repository and don't have customization in their browsers.

[clakech]

:+1:

[Mikolaj]

+1

[avodonosov]

Or used with Spidermonkey

I meant Greasemonkey...

[spiralofhope]

+1

[FichteFoll]

So, README.md may be viewed from at different URLs:
https://github.com/user/project
https://github.com/user/project/
https://github.com/user/project/blob/master/README.md
https://github.com/user/project/blob/other-branch/README.md

In the fist 3 cases rewriting of COPYING.md URL will always be the same:
<a href="/user/project/blob/master/COPYING.md" class="js-slide-to">foo</a>
But in the last case it should be
<a href="/user/project/blob/other-branch/COPYING.md" class="js-slide-to">foo</a>

I'd actually use a different appraoch. In fact, using the relative path for URLs should already work for the latter two but does not for the first two because github expects the "blob/branch/" thing.
Besides, there may also be READMEs in subfolders where this "should" work, too. But it's all realyl confusing.

[avodonosov]

@FichteFoll true.

Meantime, the javascript function provided at https://github.com/jansegre/ghrelativelinkfix-js/blob/master/fix.js already handles all 4 cases. If you open any github page with README in browser, then execute this function in javascript console, all the relative links in the README are fixed.

[FichteFoll]

Sadly I can not include this javascript code in my repos as you stated before. It does not help me when relative links work only for me because I obviously know what I wrote down in those READMEs and files.
Let's hope github includes this small snippet into their files.

[ardumont]

+1

[adamhunter]

+1

[jwarkentin]

@github Please fix this!

[jucor]

+1

[SuhasYS]

+1

[mynameistechno]

+1

[ymendel]

Sorry this took so long, folks. I actually noticed this about two months ago, and it's kind of tricky.

@jrochkind hit the nail on the head. :+1: to you, sir.

[avodonosov]

great, thanks

[excavador]

Wow! Impossible! Just in one year!

[TylerBrock]

Wait, so was this closed as #wontfix or #fixed?

[holman]

This is fixed and deployed.

[jansegre]

Seems fixed, you can see that here
https://github.com/jansegre/ghrelativelinkfix-js the link is relative and
it points to the right url, even if your url has a trailing /
https://github.com/jansegre/ghrelativelinkfix-js/

On Thu, Jan 31, 2013 at 12:02 AM, Tyler Brock [email protected]:

Wait, so was this closed as #wontfix or #fixed?

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

Att,
Jan Segre

[TylerBrock]

Thank you!

[davekinkead]

Finally! Thanks @ymendel @github

[jrochkind]

Holy moly, I thought you were closing as won't fix! You actually deployed it on github! HOORAY. This will make writing good documentation viewable on github SO MUCH EASIER. You are my hero. I haven't played with it yet to confirm it lives up to my fantasy, but i'm very excited.

[ymendel]

@TylerBrock, others : Sorry for not being clear with my comment. It was obvious to me what I meant, but then again I had just blogged / tweeted / published the help article / &c. That comment-and-close could easily be misread by anyone who hadn't seen that stuff yet.

[TylerBrock]

@ymendel PLEASE good sir, we (the internet) are just happy you did this incredible work and solved the issue. Did you see how happy the bear I posted is? HE'S CRYING FOR GOD SAKES!

[jrochkind]

(My next github doc fantasy? The syntax highlighter for ruby could realize when there was embedded markdown/rdoc in top-of-class and top-of-method comments, and render them formatted, heh).

[Maks3w]

@ymendel This fix only works if the branch name doesn't have slashes.

Link [CONTRIBUTING.md](CONTRIBUTING.md)

relative-links Works OK -> /blob/relative-links/CONTRIBUTING.md
feature/relative-links Fail -> /tree/feature/feature/relative-links/CONTRIBUTING.md (feature appears twice)

Compare rendered README.md from https://github.com/Maks3w/zf2/tree/relative-links vs https://github.com/Maks3w/zf2/tree/feature/relative-links

[jucor]

Woot woot ! Thanks !

[timholy]

@ymendel, it would be nice to be able to refer to files in other directories. As an example, suppose I want to have a bunch of screenshots in my README, but don't want to litter the top-level directory with a bunch of image files.

[jrochkind]

@timholy thats exactly what the feature four months ago lets you do. Just use relative urls. No?

[timholy]

It does work if the files are in the same directory, but that doesn't help me with my README example.
Doesn't work across directories. See similar comment by @Maks3w above, and the comments towards the bottom of http://stackoverflow.com/questions/7653483/github-relative-link-in-markdown-file

[ymendel]

It should definitely be possible to refer to other directories. The links should truly be relative, allowing you to descend into subdirectories as well as go into parent directories (using ..).

As far as I can tell, the only part of that StackOverflow post written after this feature release was a copy of the blog post itself. In fact, the original example repo made to show off the failures of relative linking, https://github.com/rynop/testRel, is a good example of how this works very well with links to other directories.

If this isn't working for you, do show me a failing case and I can see what's happening. Probably send it to [email protected], though, so it'll be easier to track.

[timholy]

Yes, you are right; I must have had a typo or something in my path. Very sorry to have troubled you.

[avodonosov]

@timofonic This is fixed around 1.5 years ago

[borismod]

@avodonosov how to use it?

[avodonosov]

@borismod just relative links to files. You write in your README.m: title - and the link works correctly, whatever branch you are currently browsing, it points to this file in the current branch.

[borismod]

@avodonosov maybe I am not getting it completely. There is a repository with a readme file. The readme file has a bunch of badges, which are images and links. I would like those images and the links to external tools, like CI, code coverage etc, to be branch related.
For example, see shellfoundry: https://github.com/QualiSystems/shellfoundry
With a link to:
https://coveralls.io/github/QualiSystems/shellfoundry?branch=develop

How can I cause the branch to be replaced when I switch to master?

[avodonosov]

@borismod , I don't know. What you describe is something opposite to what this issue is about.

[borismod]

@avodonosov 10x. My bad

[FichteFoll]

@borismod you need to change the branch GET parameter manually in each branch. There is no variable for this that github would substitute.

[borismod]

@FichteFoll thanks. I've opened a new issue #913