Skip to content

Branch relative links in markdown files #101

Closed
davekinkead opened this Issue Jan 30, 2012 · 98 comments
@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 #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
ghost commented Feb 11, 2012

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
ghost commented Feb 11, 2012

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
jumoel commented Mar 7, 2012

+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
orestes commented Mar 21, 2012

+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
ruggeri commented Apr 15, 2012

+1!

@ghost
ghost commented Apr 25, 2012
@schinen
schinen commented Apr 27, 2012

+1

@zagen
zagen commented May 2, 2012

+1

@schleyfox

+1

@ghost
ghost commented May 11, 2012

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

@waawal
waawal commented May 11, 2012

:+1:

@FichteFoll FichteFoll added a commit to FichteFoll/InsertDate that referenced this issue May 13, 2012
@FichteFoll FichteFoll Fix broken relative links ece2ff2
@patcon
patcon commented Jun 12, 2012

@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
ghost commented Jun 12, 2012

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

@dain
dain commented Jul 4, 2012

+1

@Maks3w Maks3w referenced this issue in zendframework/zf2 Jul 10, 2012
Closed

Fixes links for GitHub repository #1823

@Aqua-Ye
Aqua-Ye commented Jul 13, 2012

+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
erikw commented Jul 22, 2012

+1

@Pym
Pym commented Jul 23, 2012

+1

@songz
songz commented Jul 26, 2012

+1

@zamotivator

+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
wiseman commented Aug 9, 2012

+1

@aronwoost

+1

@cbas
cbas commented Aug 14, 2012

+1

@Maks3w Maks3w added a commit to zendframework/zf2 that referenced this issue Aug 14, 2012
@Maks3w Maks3w Remove relative links in README.md
Removes relative links to avoid confusión when they fail

github/markup#101
fb9eef8
@TylerBrock

+1

@rkylberg

+1

@katiekuwata

+1

@mmichaelis

+1

@Julian
Julian commented Sep 12, 2012

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

@jshou jshou referenced this issue in mongodb/mongo-ruby-driver Sep 21, 2012
Closed

Fix README.md links #115

@joeyespo
joeyespo commented Nov 7, 2012

+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
mnapoli commented Nov 14, 2012

+1

@stigmergic stigmergic referenced this issue in MadeInHaus/django-template Nov 16, 2012
Closed

Relative urls in md files are broken #1

@0xced
0xced commented Nov 21, 2012

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
@Brit200313

+1

@mamalisk

+1. Very important feature!

@Julian
Julian commented Nov 27, 2012

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
Julian commented Nov 27, 2012

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
slant commented Nov 28, 2012

+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
darvin commented Dec 5, 2012

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

@joeyespo joeyespo referenced this issue in joeyespo/gitpress Dec 19, 2012
Merged

Fixed simple/ link. #2

@Kyso
Kyso commented Dec 19, 2012

Yeah, this definitely needs fixing.

@joeyespo joeyespo referenced this issue in joeyespo/gitpress Dec 20, 2012
Closed

Revert #2 when GitHub fixes relative Readme URLs #5

@flyingmutant

+1

@csabapalfi csabapalfi added a commit to csabapalfi/algorithm-design-manual that referenced this issue Dec 28, 2012
@csabapalfi csabapalfi absolute links because of github/markup#84 and github/markup#101 641136c
@avodonosov

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

@pwolanin
pwolanin commented Jan 4, 2013

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
@jansegre
jansegre commented Jan 4, 2013

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
@TylerBrock
@jansegre
jansegre commented Jan 4, 2013

@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
jansegre commented Jan 4, 2013

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
clakech commented Jan 4, 2013

:+1:

@Mikolaj
Mikolaj commented Jan 4, 2013

+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
ardumont commented Jan 5, 2013

+1

@adamhunter

+1

@jwarkentin

@github Please fix this!

@jucor
jucor commented Jan 24, 2013

+1

@SuhasYS
SuhasYS commented Jan 24, 2013

+1

@ymendel
GitHub member
ymendel commented Jan 31, 2013

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.

@ymendel ymendel closed this Jan 31, 2013
@avodonosov

great, thanks

@zamotivator

Wow! Impossible! Just in one year!

@TylerBrock

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

@holman
holman commented Jan 31, 2013

This is fixed and deployed.

@jansegre
@TylerBrock

1310491635748
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
GitHub member
ymendel commented Jan 31, 2013

@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
Maks3w commented Jan 31, 2013

@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

@Maks3w Maks3w referenced this issue in zendframework/zf2 Jan 31, 2013
Closed

Making relative links in Markdown files #3627

@jucor
jucor commented Jan 31, 2013

Woot woot ! Thanks !

@timholy
timholy commented May 15, 2013

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

@timholy timholy referenced this issue in JuliaLang/julialang.github.com May 15, 2013
Closed

Blog posts on building GUIs #32

@jrochkind

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

@timholy
timholy commented May 15, 2013

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
GitHub member
ymendel commented May 15, 2013

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 support@github.com, though, so it'll be easier to track.

@timholy
timholy commented May 16, 2013

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

@addyosmani addyosmani pushed a commit to yeoman/yeoman that referenced this issue Apr 24, 2015
@granteagon granteagon Absolute url for contributing in readme
Link was originally relative, but didn't work when you were viewing
from different locations because of the way that GitHub maps repo
links in markdown.

Issue documented here: github/markup#101
e1c517b
@addyosmani addyosmani pushed a commit to yeoman/yeoman that referenced this issue Apr 24, 2015
@granteagon granteagon Absolute url for issue submission in readme
Issue submission link suffered from the same relative link issue.

github/markup#101
a3c174f
@timofonic

Any news?

@avodonosov

@timofonic This is fixed around 1.5 years ago

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Something went wrong with that request. Please try again.