39

I need to have a relative link to root of my repo from markdown file

(I need it working for any forks)

So it looks like the only way it's to provide a link to some file in the root:

the [Root](/README.md)

or

the [Root](../README.md)

(if it's located at /doc/README.md for instance)

At the same time I can refer to any folder without referring to a file

the [Doc](/doc)

But if I try to put a link to the root folder:

the [real root](/)

the [real root](../)

I'll have a link such

https://github.com/UserName/RepoName/blob/master

which unlike the

https://github.com/UserName/RepoName/blob/master/doc

refers to 404

So if I don't want to refer to README.md in the root (I could havn't it at all)

Is there any way to have such a link?

Hugo y
  • 1,421
  • 10
  • 20
Oleg Pro
  • 2,323
  • 1
  • 15
  • 23

2 Answers2

48

After some research I've found this solution:

[the real relative root of any fork](/../../)

It always points to the default branch. For me it's Ok, so it's up to you

PS

With such a trick you can also access the following abilities:

[test](/../../tree/test) - link to another branch

[doc/readme.md](/../../edit/master/doc/readme.md) - open in editor

[doc/readme.md](/../../delete/master/doc/readme.md) - ask to delete file

[doc/readme.md](/../../commits/master/doc/readme.md) - history

[doc/readme.md](/../../blame/master/doc/readme.md) - blame mode

[doc/readme.md](/../../raw/master/doc/readme.md) - raw mode (will redirect)

[doc/](/../../new/master/doc/) - ask to create new file

[doc/](/../../upload/master/doc/) - ask to upload file

[find](/../../find/test) - find file

Philzen
  • 3,945
  • 30
  • 46
Oleg Pro
  • 2,323
  • 1
  • 15
  • 23
  • 2
    I tried your relative link solution but it didn't work. I am linking **Front-end**/Projects from root `Readme.md` by `[Projects](/../../projects)`. Github returns `404`. The `url` links converts to `Front-end/Projects`. Is your solution still working? – DevelopZen Nov 29 '17 at 23:39
  • You can check this cheatsheet https://github.com/sm-artlight/github-cheatsheet and try how it works – Oleg Pro Dec 13 '17 at 17:17
  • to point to a root URL of a specific branch named **BranchName**, you can use the following syntax: `[BranchName](/../BranchName/readme.md)`. You don't need to additionally specify `../tree`. It will automatically be added – Gangula Sep 29 '21 at 08:36
  • In [gogs](https://gogs.io) I needed to use 4 ups like: `/../../../../Organization` to switch to an Organization top level relative URL in a project's *README.md*. – gridtrak Nov 09 '21 at 20:31
  • your answer did help me for what i needed. – Andre Leon Rangel Jun 28 '23 at 23:22
5

You can either link directly to the file (../README.md), or simply use a full absolute URL to link directly to the repo root: https://github.com/UserName/RepoName

Using relative links doesn't work so well on GitHub. Notice the difference between the following two URLs:

https://github.com/UserName/RepoName/tree/master/somedir
https://github.com/UserName/RepoName/blob/master/somedir/somefile

Notice that the first points to a directory and the second points to a file. Yet, after the "RepoName" we have either one of tree (for a directory) or blob for a file. Therefore relative links between the two won't work properly. On GitHub, you can't use relative links to link between a file and a directory. However, you can link between two files (as both URLs contain blob). Therefore, if you wanted to link from somefile back to README.md in the root, you could do:

[README](../README.md)

That would give you the URL:

https://github.com/UserName/RepoName/blob/master/somedir/../README.md

which would get normalized to

https://github.com/UserName/RepoName/blob/master/README.md

However, if you just want to point to the root of your Repo (or any other dir), then it is probably best to use a full URL. After all, if someone has downloaded your repo and is viewing the source locally, the relative URL to the Repo root will be different than when viewing the file on GitHub. In that case, you probably want to point them to GitHub anyway. Therefore, you should use:

[root](https://github.com/UserName/RepoName)

Another advantage of that is that if your documentation ever gets published elsewhere (perhaps a documentation hosting service), the link will still point to the GitHub repo, not some random page on the hosting service. After all, the README at your project root is not likely to get included with the contents of the docs/ dir on said hosting service.


Perhaps it would help to understand how GitHub's URL scheme presumably works. I say "presumably" as I have no inside knowledge, just a general understanding of how these types of systems are generally designed.

GitHub is not serving flat files. Rather their server is taking the URL apart, and uses the various pieces to return the proper response. The URL structure looks something like this:

https://github.com/<username>/<repository name>/<resource type>/<branch>/<resource path>

The username, repository name, resource type, and branch are rather arbitrary and just ways to GitHub to ensure they are pulling information from the correct location.

The resource type matters as they are likely not pulling files from a working tree. Rather they are pulling the files/directory listings directly from the Repo itself through a lower level. In that case, obtaining a file is very different than obtaining a directory listing and requires a different code path. Therefore, you can't request a blob (file) with aresource path that points to a tree (directory) or visa versa. The server gets confused and returns an error.

The point is that GitHub's server works on a slightly different set of rules. You can use relative URLs to move around within the resource path part of the URL, but once you change the resource type in the resource path part of the URL, then GitHub's entire scheme is broken if you don't also change the resource type in the URL. However, browsers (or HTML or Markdown) have no knowledge about that and relative URLs don't compensate for that. Therefore, you can't reliably use relative URLs to move around within a GitHub repo unless you understand all of the subtleties. Sometimes its just better to use absolute links.

Chandler Swift
  • 175
  • 1
  • 9
Waylan
  • 37,164
  • 12
  • 83
  • 109
  • 2
    there is no problem to link to a folder from file. as in my example it's possible to have `[Doc](/doc)` and it'll resolved as https://github.com/UserName/RepoName/blob/master/doc . May be the key is to make a link of the `tree/master/somedir` kind? (how to make it?) because blob/master/ to root doesn't work. Or maybe it's a github issue? – Oleg Pro Nov 04 '16 at 16:58
  • "it's possible to have `[Doc](/doc)` and it'll resolved as `github.com/UserName/RepoName/blob/master/doc`". But is *should* resolve as `github.com/UserName/RepoName/tree/master/doc`. Notice `tree` instead of `blob`, which is why you reported a 404 above. And yes, this is a GitHub specific issue. – Waylan Nov 04 '16 at 18:51
  • I just updated my answer with a breakdown of GitHub's URL scheme. Perhaps that will help clear things up. – Waylan Nov 04 '16 at 19:14
  • Thanks for the detailed explanation of why this is not possible :) but it encouraged me to further research. the problem is that if you create some doc with multiple nested levels, using the full path will destroy the navigation in project's forks. In general, the solution would be to use the file in the project root... but I found another solution finally - It's little bit tricky but it works – Oleg Pro Nov 05 '16 at 15:44
  • 2
    `tree` and `blob` auto-forward to the correct one now, so relative links work just fine. If you type `tree` in place of `blob`, it corrects itself and works, and vice versa. – Gabriel Staples Mar 26 '21 at 07:49
  • @GabrielStaples ... except for repo's root (and apparently all of these were also true back then). Someone should probably finally report it to them. – EvgenKo423 Apr 15 '21 at 18:32