Impossible to create a relative link to root of project.

[cstockton]

I can't find a way to link to the root of a repository. I am able to make links directly to the root README.md, but what I want is the default view when you visit the repository root, for example:
https://github.com/github/markup is not the same as
https://github.com/github/markup/blob/master/README.md

After inspecting the code generated by the markdown, I actually think this could be an issue with github routing. I think there is no reason for this to render a 404:
https://github.com/github/markup/blob/master/

But this view to work:
https://github.com/github/markup/

And these subfolder views to work:
https://github.com/github/markup/tree/master/script
https://github.com/github/markup/tree/master/lib

It's inconsistent and makes it impossible to create a portable README.md that links to the root of a repo.

======

How to reproduce:

Given the following tree structure:

├── dist
│   └── README.md
├── docs
│   └── README.md
└── README.md

With the following README.md files:

README.md:

# Test

  *[Main](/)* | [Docs] | [Dist]


- FAIL [Main](./) `./  ==>  /<user>/<repo>/blob/main (404)`
- FAIL [Main](/) `/  ==>  /<user>/<repo>/blob/main (404)`
- FAIL [Main](/README.md) `../  ==>  /<user>/<repo>/README.md (want /<user>/<repo>/)`


[Docs]: /docs
[Dist]: ./dist

dist/README.md:

# Test - Dist

  [Main](..) | [Docs] | *[Dist]*


- FAIL [Main](..) `..  ==>  /<user>/<repo>/blob/main (404)`
- FAIL [Main](/) `/  ==>  /<user>/<repo>/blob/main (404)`
- FAIL [Main](../) `../  ==>  /<user>/<repo>/blob/main (404)`
- FAIL [Main](/README.md) `../  ==>  /<user>/<repo>/README.md (want /<user>/<repo>/)`
- FAIL [Main](../README.md) `../  ==>  /<user>/<repo>/README.md (want /<user>/<repo>/)`


[Docs]: ../docs
[Dist]: ../dist

docs/README.md

# Test - Docs

  [Main](/README.md) | *[Docs]* | [Dist]


[Docs]: ../docs
[Dist]: ../dist

[samvilleneuve]

Hello,
For me, following works for me:

/../../

See Stackoverflow Question "Relative Link to Repo's Root from Markdown file"

[JDeuce]

While that is a workaround it means any time you move the location of the documentation file those links might need to change. While that might work in some cases, other times developers really do want the semantic from the root of the repo in their docs.

Perhaps something like if the first part of the link is a double slash // it should be from inferred as relative to the repo root, or maybe there's another convention available for this.

[mauritssilvis]

Really, all that seems to be necessary to solve this issue -- and prevent a 404 when referring to a branch's root using a relative path in a Markdown file -- would be to let the URL

https://github.com/<user>/<repo>/blob/<branch>

redirect to (or be replaced by)

https://github.com/<user>/<repo>/tree/<branch>

just like

https://github.com/<user>/<repo>/blob/<branch>/<folder>

is redirected to

https://github.com/<user>/<repo>/tree/<branch>/<folder>

I'm wondering whether the GitHub Markup project is the place to propose such a solution, though ...

[Hendrikto]

Really, all that seems to be necessary to solve this issue -- and prevent a 404 when referring to a branch's root using a relative path in a Markdown file -- would be […]

No, it would not. As JDeuce said, that would depend on where the document is located.

For dir1/README it would be .., for dir1/dir2/README it would be ../.., and so on. There is no generic way of linking to the root directory. Absolute links are no solution either, as they do not work with forks, for example.

I think /path/to/file should be relative to the root directory, and path/to/file can stay relative to the current directory.

[mauritssilvis]

No, it would not.

@Hendrikto I think we are talking about different things. You seem to emphasize the difference between relative and absolute paths.

I was trying to describe the following issue: GitHub automatically resolves relative paths when rendering Markdown -- but previously, the links resulting from relative paths to the root of a repository would result in a 404 error. So, a link with the relative path .. in a Markdown file dir1/dir2/README.md would be rendered as an absolute URL to dir1. On the other hand, if we had a file https://github.com/github/markup/blob/master/test/README.md, a relative link .. in this file would be rendered as https://github.com/github/markup/blob/master/, but it would show us a 404 error instead of the main repository page. This problem seems to have been solved now, so I think the current issue can be closed.

[killroy42]

I don't like it, but the best I could figure is something like /../../../../../../../../<user>/<repo>/<path>

Of course this will not hit the right files in multiple branches, etc. But for referencing something like a wiki page it might work.

[mauritssilvis]

I don't like it, but the best I could figure is something like /../../../../../../../../<user>/<repo>/<path>

Of course this will not hit the right files in multiple branches, etc. But for referencing something like a wiki page it might work.

Relative paths in Markdown files work well as long as you refer to files on the same branch within the same repository. The GitHub web environment will render these paths as absolute URLs of the form https://github.com/<user>/<repo>/blob/<branch or tag>/<path>, where <branch or tag> represents the branch or tag that is selected in the web environment. More importantly, these relative paths are valid when someone clones the repository to their local file system.

On the other hand, relative paths in Markdown files that point to a different repository or branch might be rendered correctly in the GitHub web environment, but will likely point to a non-existing directory in a locally cloned repository. I would, therefore, recommend using absolute URLs in case you want to refer to the (web version) of a file in a different GitHub repository or on a different branch (of the same repository). As noted above, these URLs take the form https://github.com/<user>/<repo>/blob/<branch or tag>/<path>.

[killroy42]

Thanks for the elaboration. I'm aware of that. But in my case, all I wanted was to link to the wiki from the readme.md file, and have that link work from any branch/tag or version of that readme.md file. So the method above does that without needing to invoke the domain. It does however force the user and repo, so would not work on a fork, etc. It would be nice to have the option to reference a file in the same repo, "root-relative", which is, de facto, absolute within the same repository. Normally this would be done via /<path>, but in GitHub markdown that is somehow treated like ./<path> or event <path>, which is bizarre and redundant.

[mauritssilvis]

Thanks for the elaboration. I'm aware of that. But in my case, all I wanted was to link to the wiki from the readme.md file, and have that link work from any branch/tag or version of that readme.md file. So the method above does that without needing to invoke the domain. It does however force the user and repo, so would not work on a fork, etc. It would be nice to have the option to reference a file in the same repo, "root-relative", which is, de facto, absolute within the same repository. Normally this would be done via /<path>, but in GitHub markdown that is somehow treated like ./<path> or event <path>, which is bizarre and redundant.

I understand your use case, but I don't think the way GitHub renders Markdown as HTML is so bizarre. After all, web browsers and file systems treat absolute paths differently. A web browser will treat /<path> relative to the domain, so it'll turn it into https://github.com/<path>. On a local file system, /<path> will be relative to the file system root, which is unlikely to work as expected for the wiki references you mention. Why would GitHub render links in a way that works in the web version of your repository but will fail for local clones (and, as you say, forks)? Besides, both common ways of processing absolute paths are different than the repository-relative paths you propose, so I don't expect GitHub will introduce the feature you desire.

Consider your repository and your wiki as separate entities and use absolute URLs from your repository to your wiki (so these references also work in forks and local clones) or include the wiki pages in your repository and use relative references as you desire :)

[killroy42]

But that's the point: It does NOT do this. If it did, that would be fine and we could just use /<user>/<path>. But it converts such a path into a relative path, which is NOT what web browsers would do if that's the url given in an anchor tag.

[mauritssilvis]

But that's the point: It does NOT do this. If it did, that would be fine and we could just use /<user>/<path>. But it converts such a path into a relative path, which is NOT what web browsers would do if that's the url given in an anchor tag.

Right, it doesn't do this -- and it shouldn't, because it wouldn't be fine. The paths you want to use wouldn't work in local clones and forks. In other words, the feature you want won't work consistently in different environments and, thus, isn't supported. Or, to put it more succinctly, don't expect paths starting with a slash to work -- and consider using either of the two options I mentioned previously to refer to wiki pages.

[github-actions]

Stale issue message

[Hendrikto]

This issue is not stale. I am still very interested in this, and I am sure others are too.

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[Hendrikto]

Again: This is not stale. The issue is still relevant. We still want a solution.