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 #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]

👍

[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]

👍

[patcon]

@davekinkead 👍

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]

👍

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

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

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

—
Reply to this email directly or view it on GitHubhttps://github.com//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 support@github.com, 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