New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Support branch relative links in README.md on root of repo #84

Closed
doapp-ryanp opened this Issue Oct 12, 2011 · 81 comments

Comments

Projects
None yet
@doapp-ryanp

doapp-ryanp commented Oct 12, 2011

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

This comment has been minimized.

Show comment
Hide comment
@ralphschindler

ralphschindler Nov 1, 2011

I would like this as well so I can write documentation that references the code.

ralphschindler commented Nov 1, 2011

I would like this as well so I can write documentation that references the code.

@mloskot

This comment has been minimized.

Show comment
Hide comment
@mloskot

mloskot Dec 19, 2011

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.

mloskot commented Dec 19, 2011

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

This comment has been minimized.

Show comment
Hide comment
@cbeams

cbeams Dec 20, 2011

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

cbeams commented Dec 20, 2011

+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

This comment has been minimized.

Show comment
Hide comment
@technoweenie

technoweenie Dec 20, 2011

Contributor

We tried adding a <base> tag for this, but it causes problems with other relative links on the site.

Contributor

technoweenie commented Dec 20, 2011

We tried adding a <base> tag for this, but it causes problems with other relative links on the site.

@ralphschindler

This comment has been minimized.

Show comment
Hide comment
@ralphschindler

ralphschindler Dec 20, 2011

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

ralphschindler commented Dec 20, 2011

@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

This comment has been minimized.

Show comment
Hide comment
@bpierre

bpierre Jan 20, 2012

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)?

bpierre commented Jan 20, 2012

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

This comment has been minimized.

Show comment
Hide comment
@doapp-ryanp

doapp-ryanp Jan 20, 2012

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.

doapp-ryanp commented Jan 20, 2012

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

This comment has been minimized.

Show comment
Hide comment
@pulkitsinghal

pulkitsinghal Feb 10, 2012

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

pulkitsinghal commented Feb 10, 2012

@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

This comment has been minimized.

Show comment
Hide comment
@dblock

dblock Feb 20, 2012

+1, this is super painful for open-sourcing wiki-like content

dblock commented Feb 20, 2012

+1, this is super painful for open-sourcing wiki-like content

@davejamesmiller

This comment has been minimized.

Show comment
Hide comment
@davejamesmiller

davejamesmiller commented Feb 21, 2012

+1

@technoweenie

This comment has been minimized.

Show comment
Hide comment
@technoweenie

technoweenie Feb 21, 2012

Contributor

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 support@github.com if you want to talk about GitHub issues. This is out of scope of this small OSS library.

Contributor

technoweenie commented Feb 21, 2012

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 support@github.com if you want to talk about GitHub issues. This is out of scope of this small OSS library.

@dblock

This comment has been minimized.

Show comment
Hide comment
@dblock

dblock Feb 21, 2012

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

dblock commented Feb 21, 2012

@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

This comment has been minimized.

Show comment
Hide comment
@davejamesmiller

davejamesmiller Feb 22, 2012

@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 support@github.com as you said.

Cheers

davejamesmiller commented Feb 22, 2012

@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 support@github.com as you said.

Cheers

@odalet

This comment has been minimized.

Show comment
Hide comment
@odalet

odalet Feb 25, 2012

+1
It's all the more a hassle as relative links work when clicked from an explicitly opened readme.md

odalet commented Feb 25, 2012

+1
It's all the more a hassle as relative links work when clicked from an explicitly opened readme.md

@RobertDober

This comment has been minimized.

Show comment
Hide comment
@RobertDober

RobertDober Mar 3, 2012

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

RobertDober commented Mar 3, 2012

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

sol added a commit to sol/gentoo-haskell that referenced this issue Apr 8, 2012

Fix broken link in README
I first tried to use some relative URL, but this does not work reliable
(see github/markup#84).

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

@breerly

This comment has been minimized.

Show comment
Hide comment
@breerly

breerly May 31, 2012

+1 - no go?

breerly commented May 31, 2012

+1 - no go?

@ralphschindler

This comment has been minimized.

Show comment
Hide comment
@ralphschindler

ralphschindler Jun 1, 2012

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

ralphschindler commented Jun 1, 2012

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

This comment has been minimized.

Show comment
Hide comment
@psi-4ward

psi-4ward commented Jun 11, 2012

+1

@aschempp

This comment has been minimized.

Show comment
Hide comment
@aschempp

aschempp Jun 11, 2012

+1
especially also important for relative image links!!

aschempp commented Jun 11, 2012

+1
especially also important for relative image links!!

@monobasic

This comment has been minimized.

Show comment
Hide comment
@monobasic

monobasic commented Jun 18, 2012

+1

2 similar comments
@danmunn

This comment has been minimized.

Show comment
Hide comment
@danmunn

danmunn commented Jun 21, 2012

+1

@0xced

This comment has been minimized.

Show comment
Hide comment
@0xced

0xced commented Jul 1, 2012

+1

@robertwahler

This comment has been minimized.

Show comment
Hide comment
@robertwahler

robertwahler Jul 27, 2012

+1

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

robertwahler commented Jul 27, 2012

+1

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

@lorrin

This comment has been minimized.

Show comment
Hide comment
@lorrin

lorrin Aug 15, 2012

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

lorrin commented Aug 15, 2012

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

@est

This comment has been minimized.

Show comment
Hide comment
@est

est Aug 29, 2012

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

est commented Aug 29, 2012

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

@jaspermdegroot

This comment has been minimized.

Show comment
Hide comment
@jaspermdegroot

jaspermdegroot Sep 17, 2012

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

jaspermdegroot commented Sep 17, 2012

+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

This comment has been minimized.

Show comment
Hide comment
@colszowka

colszowka Sep 18, 2012

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!

colszowka commented Sep 18, 2012

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!

@colszowka

This comment has been minimized.

Show comment
Hide comment
@doapp-ryanp

This comment has been minimized.

Show comment
Hide comment
@doapp-ryanp

doapp-ryanp Feb 1, 2013

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

doapp-ryanp commented Feb 1, 2013

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

@ralphschindler

This comment has been minimized.

Show comment
Hide comment
@ralphschindler

ralphschindler Feb 1, 2013

Great! Thanks to all involved!
-ralph

ralphschindler commented Feb 1, 2013

Great! Thanks to all involved!
-ralph

@dhladky

This comment has been minimized.

Show comment
Hide comment
@dhladky

dhladky Feb 4, 2013

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.

dhladky commented Feb 4, 2013

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

This comment has been minimized.

Show comment
Hide comment
@colszowka

colszowka Feb 4, 2013

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

colszowka commented Feb 4, 2013

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

@dhladky

This comment has been minimized.

Show comment
Hide comment
@dhladky

dhladky Feb 4, 2013

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.

dhladky commented Feb 4, 2013

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

This comment has been minimized.

Show comment
Hide comment
@colszowka

colszowka Feb 4, 2013

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

colszowka commented Feb 4, 2013

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

This comment has been minimized.

Show comment
Hide comment
@dhladky

dhladky Feb 4, 2013

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.

dhladky commented Feb 4, 2013

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

This comment has been minimized.

Show comment
Hide comment
@colszowka

colszowka Feb 4, 2013

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

colszowka commented Feb 4, 2013

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

@dhladky

This comment has been minimized.

Show comment
Hide comment
@dhladky

dhladky Feb 4, 2013

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

dhladky commented Feb 4, 2013

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

@swmcc swmcc referenced this issue May 25, 2013

Closed

Fix relative links #3

thlorenz added a commit to thlorenz/node-browserify that referenced this issue Jan 21, 2014

adding browserify tools wiki link
- all tools that were there are now in that wiki, so I removed them from that section
- fixed list of transforms wiki link (relative links not working: github/markup#84)

substack added a commit to browserify/browserify that referenced this issue Jan 22, 2014

adding browserify tools wiki link
- all tools that were there are now in that wiki, so I removed them from that section
- fixed list of transforms wiki link (relative links not working: github/markup#84)

psibre added a commit to marytts/marytts-txt2wav that referenced this issue May 27, 2015

@brauliobo

This comment has been minimized.

Show comment
Hide comment
@brauliobo

brauliobo Aug 1, 2015

+1 to variables support (branch, etc)

brauliobo commented Aug 1, 2015

+1 to variables support (branch, etc)

@muescha

This comment has been minimized.

Show comment
Hide comment
@muescha

muescha Sep 18, 2015

+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

muescha commented Sep 18, 2015

+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

This comment has been minimized.

Show comment
Hide comment
@avodonosov

avodonosov Nov 22, 2015

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

avodonosov commented Nov 22, 2015

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

@muescha

This comment has been minimized.

Show comment
Hide comment
@muescha

muescha Dec 2, 2015

@avodonosov in pull requests its still not implemented

muescha commented Dec 2, 2015

@avodonosov in pull requests its still not implemented

@avodonosov

This comment has been minimized.

Show comment
Hide comment
@avodonosov

avodonosov Dec 2, 2015

@muescha @tiabobia ah, pull requests. Probably discussing it in a closed issue might be inefficient. Also, have you seen #285 ?

avodonosov commented Dec 2, 2015

@muescha @tiabobia ah, pull requests. Probably discussing it in a closed issue might be inefficient. Also, have you seen #285 ?

@muescha

This comment has been minimized.

Show comment
Hide comment
@muescha

muescha Dec 7, 2015

@avodonosov ok i will open a new issue for this

here is the number: #576

muescha commented Dec 7, 2015

@avodonosov ok i will open a new issue for this

here is the number: #576

@OmgImAlexis

This comment has been minimized.

Show comment
Hide comment
@OmgImAlexis

OmgImAlexis Sep 8, 2016

Did this ever get fixed/implemented?

OmgImAlexis commented Sep 8, 2016

Did this ever get fixed/implemented?

@AxelStrem

This comment has been minimized.

Show comment
Hide comment
@AxelStrem

AxelStrem Oct 26, 2016

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

AxelStrem commented Oct 26, 2016

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

@sc0ttkclark

This comment has been minimized.

Show comment
Hide comment
@sc0ttkclark

sc0ttkclark Jan 3, 2017

This idea lives again in #913!

sc0ttkclark commented Jan 3, 2017

This idea lives again in #913!

@lorddev

This comment has been minimized.

Show comment
Hide comment
@lorddev

lorddev Aug 4, 2018

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

lorddev commented Aug 4, 2018

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

@rzr

This comment has been minimized.

Show comment
Hide comment
@rzr

rzr commented Aug 10, 2018

It seems it has been fixed no?

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

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