192

Let's say I have two points within the same git hub wiki page, which for this we'll call place 1 and place 2. 

##Title

###Place 1

Hello, this is some text to fill in this, [here](place2), is a link to the second place.

###Place 2

Place one has the fun times of linking here, but I can also link back [here](place1).

An alternative is a ToC.

##Title
[ToC]
###Place 1
###Place 2

Is there any way to do this? Note - seen this so I'll assume it's on topic. Also, that deals with going between files, this one deals with going between the same file.

Alberto S.
  • 1,805
  • 23
  • 39
Alexander Craggs
  • 7,874
  • 4
  • 24
  • 46
  • 1
    possible duplicate of [How do you create & link to a named anchor in Multimarkdown](http://stackoverflow.com/questions/6695439/how-do-you-create-link-to-a-named-anchor-in-multimarkdown) – flyx Jan 16 '15 at 09:58
  • 2
    [this answer](http://stackoverflow.com/a/15843220/347964) is probably the relevant one for you. – flyx Jan 16 '15 at 09:59

6 Answers6

254

This works on Github:

## Title

### Place 1

Hello, this is some text to fill in this, [here](#place-2), is a link to the second place.

### Place 2

Place one has the fun times of linking here, but I can also link back [here](#place-1).

### Place's 3: other example

Place one has the fun times of linking here, but I can also link back [here](#places-3-other-example).

Summary of the conversion rules:

  • punctuation marks will be dropped
  • leading white spaces will be dropped
  • upper case will be converted to lower
  • spaces between letters will be converted to -

A good example document with plenty of links and formatting is LivingSocial API Design Guide

Alberto S.
  • 1,805
  • 23
  • 39
FelixEnescu
  • 4,664
  • 2
  • 33
  • 34
  • 7
    Note that the ref link itself must be coded as lower case. Using the example above, if you link to `[here](#Place-2)`, the link won't work. Note how in the example, the heading is called "Place 2" and the link to it is (properly) called `[here](#place-2)`. – DaveL17 Nov 19 '17 at 15:27
  • 8
    If you have 2 or more headings with the same name `Place` the links will be named `place`, `place-1`, `place-2`, etc. Then if you also have an explicit header `Place 2` its link will be `place-2-1`. – Kevin May 10 '18 at 13:29
  • 1
    The answer is still helpful as it works in Gitlab Wiki. The html method (using anchor tag in the gitlab wiki) doesn't work. I understand the question was about github though. – Nditah Oct 09 '19 at 12:20
  • It does not seems to be supported in BitBucket. I use the anchor instead. – рüффп Jul 09 '20 at 10:38
  • Only thing is, this does not seem to be officially documented by github, so it relies on reverse-engineered rules, which could change without notice, thus breaking all your links. You are better off using the `` or `text, html or markdown` mentioned in @bcattle's answer. – Oliver Mar 16 '21 at 02:28
40

It's also possible to create named custom anchors, if for example you have a bunch of (sub-)headings with the same name. To do this with a header insert an HTML tag:

<h4 id="login-optional-fields">
Optional Fields
</h4>

Then link to it by the ID attribute:

[see above](#login-optional-fields)

Also adding an anchor tag directly to the document works as well:

<a id="my-anchor"></a>
bcattle
  • 12,115
  • 6
  • 62
  • 82
  • 2
    Thank you, this solution works a treat and for one reason. Changes to GIT markdown last year prevent headings being add as `#my heading` anymore it has to be `# my heading` and adding a space in the anchor like `(# my-heading)` does not work – MitchellK Apr 30 '18 at 10:11
  • this worked for .md files as well. I use gatsby for my tech blog and wanted to create a hyperlink to a section within the page itself. Thanks! – Ayush Mandowara Jan 28 '21 at 09:13
  • Very cool and does not depend on implementation details of how github converts title to anchor (which could likely change any time without notice). It even works with an image: `![Your Image](docs/your-image.png)` then `[your image](#image)` links to the image! This works in github and pycharm IDE's markdown previewer. – Oliver Mar 16 '21 at 02:25
7

Copied from GitHub Gist - the original post located here

To create anchor links that jump down to different sections of a README (as in an interactive table of contents), first create a heading:

#Real Cool Heading

The anchor link for that heading is the lowercase heading name with dashes where there are spaces. You can always get the anchor name by visiting the README on Github.com and clicking on the anchor that appears when you hover to the left of the heading. Copy everything starting at the #:

#real-cool-heading

Wherever you want to link to your Real Cool Heading section, put your desired text in brackets, followed by the anchor link in parentheses:

[Go to Real Cool Heading section](#real-cool-heading)
EladTal
  • 2,167
  • 1
  • 18
  • 10
5

Accepted answer didnt work for me coz my heading was also a link :

Before (Didnt work):

Table of contents 

 1. [Header Name](#header-name)


### [Header Name](https://google.com)

After (worked for me) :

Table of contents 

 1. [Header Name](#header-name)


### Header Name

https://google.com

This is when u dont want to have html and want to work with accepted solution with some tradeoffs in readme.

Jay Teli
  • 530
  • 1
  • 11
  • 19
1

example 1:

##Title

###Place 1<span id="place1">HelloWorld</span>

Hello, this is some text to fill in this, [here](#place2), is a link to the second place.

###Place 2<span id="place2">HelloWorld</span>

Place one has the fun times of linking here, but I can also link back [here](#place1).

Here is a version that could jump from place1 to place2 and jump from place2 to place1

##Title

###[Place 1](#Place-2)<span id="place1">HelloWorld</span>

Hello, this is some text to fill in this, [here](#place2), is a link to the second 
place.

###Place 2(#Place-1)<span id="place2">HelloWorld</span>

Place one has the fun times of linking here, but I can also link back [here](#place1).
J.Zhao
  • 2,250
  • 1
  • 14
  • 12
0

Unfortunately, it appears that GitHub wiki strips all of the "id=.." tags from custom HTML that you add to a wiki page, so the only working anchors within a page are the headings.

cpurdy
  • 1,177
  • 5
  • 12