103

How do I create a link from a README.md file to a Wiki page in github? Every example seems to show linking from one wiki page to another wiki page, or from one README file to another file in the repository. But none that show linking from one to the other

veilig
  • 5,085
  • 10
  • 48
  • 86
  • You're right. "from one README file to another file in the repository" does work, official ref https://help.github.com/articles/relative-links-in-readmes/ official blog https://github.com/blog/1395-relative-links-in-markup-files , see also https://bibwild.wordpress.com/2013/01/30/awesome-github-feature-no-excuse-for-not-having-good-docs-anymore/ . – Stéphane Gourichon Feb 26 '15 at 17:28
  • 1
    Insightful about why link from README to wiki is not so desirable: "Sure, you could link out to your wiki — but wiki isn’t versioned along with source code, and you want to link to the version of the docs that go along with the exact snapshot of the source repo you’re looking at. Sure, you could link out using absolute URL hyperlinks — but same problem, you’re always linking to master, when you want to link to the file in the same snapshot the reader is looking at the README in." Source: https://bibwild.wordpress.com/2013/01/30/awesome-github-feature-no-excuse-for-not-having-good-docs-anymore/ – Stéphane Gourichon Mar 02 '15 at 08:12

5 Answers5

109

I just came across this question and saw that this was impossible, but stubbornly kept trying anyway. Good news, because this actually can be done with relative links!

If you look at the documentation for relative links on GitHub, you can see that it supports ./ and ../ operands.

Given that your README is located at:

https://github.com/<user-name>/<repo-name>/blob/master/README.md

... and the wiki is located at:

https://github.com/<user-name>/<repo-name>/wiki

... that means you can just crawl back from the README to the wiki, like so:

[My Awesome Wiki](../../wiki)

Update: As some people have pointed out in the comments (thanks!), please be aware that these relative links will break on clones and forks, so be sure to weigh that into your decision!

jmar777
  • 38,796
  • 11
  • 66
  • 64
  • 16
    Interesting, but notice that the README.md may be viewed from a local clone instead of the web. In that case, the only thing that works is a link with absolute URL. – Stéphane Gourichon Feb 26 '15 at 17:22
  • 1
    Good point, @StéphaneGourichon, I hadn't considered local viewing of the Readme. Although I suppose if relative links are desired that's an acceptable limitation. – jmar777 Mar 02 '15 at 04:38
  • 2
    You can clone the wiki locally as a separate git repo: http://stackoverflow.com/questions/15080848/how-do-i-clone-a-github-wiki – EriF89 Apr 13 '15 at 09:02
  • 4
    Word of warning: When viewing single files like a `README.md` and a specific blob for an commit, this won't work. – kaiser Apr 10 '16 at 17:47
  • As mentioned by Stephane Gourichon, relative links aren't always the way to go. Another example is if you want your package to be installable via a third party open source platform. For Python, this is PyPi. PyPi will load in the description, but all the relative links will be broken. You need to go with absolute URLs in this case. – cgnorthcutt Jul 06 '18 at 17:36
79

You would have to use an absolute URL as opposed to a relative one.

For example:

[Sites Using React](https://github.com/facebook/react/wiki/Sites-Using-React)
maxdeviant
  • 1,161
  • 9
  • 10
  • 5
    ok, thats what I thought - just wanted to make sure there wasn't a better way. – veilig May 22 '14 at 13:21
  • 2
    In the doc linked to by @jmar777, it cautions about using absolute URLs: "Users cloning your repository will have a much harder time getting the links to work than expected." – Dave Sexton May 24 '16 at 19:55
  • 2
    @DaveSexton That's specifically referring to linking to other files in the repository (which will always be relative to the README). When linking to something external (like a wiki), you want to use absolute URLs. – maxdeviant Sep 20 '17 at 15:25
4

I am using GitLab. My link to my Wiki page looks like this.

Checkout the [Wiki page](/%2E%2E/wikis/Welcome)

I tried the other recommendations that are posted here but it kept changing the URL with re-writes that broke the link.

LinuxGuru
  • 341
  • 2
  • 11
3

I found that I needed to crawl back 3 levels versus 2 levels as descreibed in jmar777's approach.

When I used 

../../wiki

The link generated was https://github.com/<username>/blob/wiki

I needed to use:

../../../wiki

This generated https://github.com/<username>/wiki

Grendel
  • 43
  • 5
1

Just to add on this one, if you want to refer to your repo file from inside wiki use ../../blob/master/. Combined with the answer from jmar777 this allows to completely integrate code and wiki and remove a need for bloated readme.md.

To make it work locally as well as your file structure would have to be

./Wiki/YourWikiRepo
./blob/master/YourCodeRepo
Hizqeel
  • 947
  • 3
  • 20
  • 23
DfAC
  • 385
  • 2
  • 6