Branch relative links in markdown files #101

Closed
davekinkead opened this Issue Jan 30, 2012 · 105 comments

Comments

Projects
None yet
@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

This comment has been minimized.

Show comment
Hide comment
@pulkitsinghal

pulkitsinghal Feb 10, 2012

+1 this feature is badly needed

+1 this feature is badly needed

@ghost

This comment has been minimized.

Show comment
Hide comment
@ghost

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

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

This comment has been minimized.

Show comment
Hide comment
@pulkitsinghal

pulkitsinghal Feb 11, 2012

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.

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

This comment has been minimized.

Show comment
Hide comment
@ghost

ghost Feb 11, 2012

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

ghost commented Feb 11, 2012

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

@pulkitsinghal

This comment has been minimized.

Show comment
Hide comment
@pulkitsinghal

pulkitsinghal Feb 11, 2012

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.

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

This comment has been minimized.

Show comment
Hide comment
@davekinkead

davekinkead Feb 11, 2012

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.

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

This comment has been minimized.

Show comment
Hide comment
@jumoel

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

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

This comment has been minimized.

Show comment
Hide comment
@orestes

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

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

This comment has been minimized.

Show comment
Hide comment
@ruggeri

ruggeri Apr 15, 2012

+1!

ruggeri commented Apr 15, 2012

+1!

@fabiokung

This comment has been minimized.

Show comment
Hide comment
@fabiokung

fabiokung Apr 24, 2012

👍

👍

@ghost

This comment has been minimized.

Show comment
Hide comment
@ghost

ghost Apr 25, 2012

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

ghost commented Apr 25, 2012

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

@schinen

This comment has been minimized.

Show comment
Hide comment
@schinen

schinen Apr 27, 2012

+1

schinen commented Apr 27, 2012

+1

@zagen

This comment has been minimized.

Show comment
Hide comment
@zagen

zagen May 2, 2012

+1

zagen commented May 2, 2012

+1

@schleyfox

This comment has been minimized.

Show comment
Hide comment
@schleyfox

schleyfox May 11, 2012

+1

+1

@ghost

This comment has been minimized.

Show comment
Hide comment
@ghost

ghost May 11, 2012

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

ghost commented May 11, 2012

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

@waawal

This comment has been minimized.

Show comment
Hide comment
@waawal

waawal May 11, 2012

👍

waawal commented May 11, 2012

👍

FichteFoll added a commit to FichteFoll/InsertDate that referenced this issue May 13, 2012

@patcon

This comment has been minimized.

Show comment
Hide comment
@patcon

patcon Jun 12, 2012

@davekinkead 👍

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

patcon commented Jun 12, 2012

@davekinkead 👍

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

@FichteFoll

This comment has been minimized.

Show comment
Hide comment
@FichteFoll

FichteFoll Jun 12, 2012

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

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

@ghost

This comment has been minimized.

Show comment
Hide comment
@ghost

ghost Jun 12, 2012

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

ghost commented Jun 12, 2012

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

@dain

This comment has been minimized.

Show comment
Hide comment
@dain

dain Jul 4, 2012

+1

dain commented Jul 4, 2012

+1

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

Closed

Fixes links for GitHub repository #1823

@sindresorhus

This comment has been minimized.

Show comment
Hide comment
@sindresorhus

sindresorhus Jul 10, 2012

👍

👍

@Aqua-Ye

This comment has been minimized.

Show comment
Hide comment
@Aqua-Ye

Aqua-Ye Jul 13, 2012

+1

Aqua-Ye commented Jul 13, 2012

+1

@jansegre

This comment has been minimized.

Show comment
Hide comment
@jansegre

jansegre Jul 22, 2012

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

+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

This comment has been minimized.

Show comment
Hide comment
@erikw

erikw Jul 22, 2012

+1

erikw commented Jul 22, 2012

+1

@Pym

This comment has been minimized.

Show comment
Hide comment
@Pym

Pym Jul 23, 2012

+1

Pym commented Jul 23, 2012

+1

@songz

This comment has been minimized.

Show comment
Hide comment
@songz

songz Jul 26, 2012

+1

songz commented Jul 26, 2012

+1

@excavador

This comment has been minimized.

Show comment
Hide comment
@excavador

excavador Jul 27, 2012

+1

+1

@jrochkind

This comment has been minimized.

Show comment
Hide comment
@jrochkind

jrochkind Aug 9, 2012

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

+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

This comment has been minimized.

Show comment
Hide comment
@wiseman

wiseman Aug 9, 2012

+1

wiseman commented Aug 9, 2012

+1

@aronwoost

This comment has been minimized.

Show comment
Hide comment
@aronwoost

aronwoost Aug 13, 2012

+1

+1

@sebdeckers

This comment has been minimized.

Show comment
Hide comment
@sebdeckers

sebdeckers Aug 14, 2012

+1

+1

Maks3w added a commit to zendframework/zendframework that referenced this issue Aug 14, 2012

Remove relative links in README.md
Removes relative links to avoid confusión when they fail

github/markup#101
@petrkozorezov

This comment has been minimized.

Show comment
Hide comment
@petrkozorezov

petrkozorezov Aug 17, 2012

+1

@TylerBrock

This comment has been minimized.

Show comment
Hide comment
@TylerBrock

TylerBrock Aug 20, 2012

+1

+1

@rkylberg

This comment has been minimized.

Show comment
Hide comment
@rkylberg

rkylberg Aug 28, 2012

+1

+1

@katiekuwata

This comment has been minimized.

Show comment
Hide comment
@katiekuwata

katiekuwata Aug 29, 2012

+1

+1

@mmichaelis

This comment has been minimized.

Show comment
Hide comment
@mmichaelis

mmichaelis Sep 3, 2012

+1

+1

@jwarkentin

This comment has been minimized.

Show comment
Hide comment
@jwarkentin

jwarkentin Jan 22, 2013

@github Please fix this!

@github Please fix this!

@jucor

This comment has been minimized.

Show comment
Hide comment
@jucor

jucor Jan 24, 2013

+1

jucor commented Jan 24, 2013

+1

@SuhasYS

This comment has been minimized.

Show comment
Hide comment
@SuhasYS

SuhasYS Jan 24, 2013

+1

SuhasYS commented Jan 24, 2013

+1

@mynameistechno

This comment has been minimized.

Show comment
Hide comment
@mynameistechno

mynameistechno Jan 26, 2013

+1

@ymendel

This comment has been minimized.

Show comment
Hide comment
@ymendel

ymendel Jan 31, 2013

Contributor

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. 👍 to you, sir.

Contributor

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. 👍 to you, sir.

@ymendel ymendel closed this Jan 31, 2013

@avodonosov

This comment has been minimized.

Show comment
Hide comment
@avodonosov

avodonosov Jan 31, 2013

great, thanks

great, thanks

@excavador

This comment has been minimized.

Show comment
Hide comment
@excavador

excavador Jan 31, 2013

Wow! Impossible! Just in one year!

Wow! Impossible! Just in one year!

@TylerBrock

This comment has been minimized.

Show comment
Hide comment
@TylerBrock

TylerBrock Jan 31, 2013

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

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

@holman

This comment has been minimized.

Show comment
Hide comment
@holman

holman Jan 31, 2013

This is fixed and deployed.

holman commented Jan 31, 2013

This is fixed and deployed.

@jansegre

This comment has been minimized.

Show comment
Hide comment
@jansegre

jansegre Jan 31, 2013

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 notifications@github.comwrote:

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

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 notifications@github.comwrote:

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

This comment has been minimized.

Show comment
Hide comment
@TylerBrock

TylerBrock Jan 31, 2013

1310491635748
Thank you!

1310491635748
Thank you!

@davekinkead

This comment has been minimized.

Show comment
Hide comment
@davekinkead

davekinkead Jan 31, 2013

Finally! Thanks @ymendel @github

Finally! Thanks @ymendel @github

@jrochkind

This comment has been minimized.

Show comment
Hide comment
@jrochkind

jrochkind Jan 31, 2013

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.

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

This comment has been minimized.

Show comment
Hide comment
@ymendel

ymendel Jan 31, 2013

Contributor

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

Contributor

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

This comment has been minimized.

Show comment
Hide comment
@TylerBrock

TylerBrock Jan 31, 2013

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

@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

This comment has been minimized.

Show comment
Hide comment
@jrochkind

jrochkind Jan 31, 2013

(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).

(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

This comment has been minimized.

Show comment
Hide comment
@Maks3w

Maks3w 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 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/zendframework Jan 31, 2013

Closed

Making relative links in Markdown files #3627

@jucor

This comment has been minimized.

Show comment
Hide comment
@jucor

jucor Jan 31, 2013

Woot woot ! Thanks !

jucor commented Jan 31, 2013

Woot woot ! Thanks !

@timholy

This comment has been minimized.

Show comment
Hide comment
@timholy

timholy 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 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

This comment has been minimized.

Show comment
Hide comment
@jrochkind

jrochkind May 15, 2013

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

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

@timholy

This comment has been minimized.

Show comment
Hide comment
@timholy

timholy 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

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

This comment has been minimized.

Show comment
Hide comment
@ymendel

ymendel May 15, 2013

Contributor

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.

Contributor

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

This comment has been minimized.

Show comment
Hide comment
@timholy

timholy May 16, 2013

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

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 pushed a commit to yeoman/yeoman that referenced this issue Apr 24, 2015

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

addyosmani pushed a commit to yeoman/yeoman that referenced this issue Apr 24, 2015

Absolute url for issue submission in readme
Issue submission link suffered from the same relative link issue.

github/markup#101
@avodonosov

This comment has been minimized.

Show comment
Hide comment
@avodonosov

avodonosov Nov 22, 2015

@timofonic This is fixed around 1.5 years ago

@timofonic This is fixed around 1.5 years ago

@borismod

This comment has been minimized.

Show comment
Hide comment
@borismod

borismod Jul 12, 2016

@avodonosov how to use it?

@avodonosov how to use it?

@avodonosov

This comment has been minimized.

Show comment
Hide comment
@avodonosov

avodonosov Jul 12, 2016

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

This comment has been minimized.

Show comment
Hide comment
@borismod

borismod Jul 12, 2016

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

This comment has been minimized.

Show comment
Hide comment
@avodonosov

avodonosov Jul 12, 2016

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

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

@borismod

This comment has been minimized.

Show comment
Hide comment
@borismod

borismod Jul 12, 2016

@avodonosov 10x. My bad

@avodonosov 10x. My bad

@FichteFoll

This comment has been minimized.

Show comment
Hide comment
@FichteFoll

FichteFoll Jul 12, 2016

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

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

@borismod

This comment has been minimized.

Show comment
Hide comment
@borismod

borismod Jul 12, 2016

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

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment