Relative Link to Repo's Root from Markdown file

Question

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?

Solution 1

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

Solution 2

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.