Links are used to jump to a particular page or heading within a Wiki, they can also be used to navigate to other websites or to download files (just like links on any web page).

Markdown links can be direct (normal type) links or can be reference-style links. Reference style links do exactly the same as direct links but make the Markdown easier to read (but in turn are more complicated to implement).

This section concerns itself with direct links (these are by far the most widely used) section 9.7 covers reference-style links.

Direct links can do the following:

All of these are covered in the next sections:

⬆️ Top

This is the easiest (and probably most common) type of link, there are different versions:

Taking each in turn:

⬆️ Top

Let’s say we want to put a link to the Google UK website on a Wiki page, at its most basic it would look like this:

This is a link to https://google.co.uk.

The Markdown for this is very easy (in fact there is no Markdown), GitHub automatically detects URLs and converts them to a web link:

This is a link to https://google.co.uk.

This is a link to https://www.google.co.uk.

This is a link to www.google.co.uk.

The equivalent HTML for the above is:

This is a link to <a href="https://google.co.uk">
https://google.co.uk</a>

This is a link to <a href="https://www.google.co.uk">
https://www.google.co.uk</a>

This is a link to <a href="www.google.co.uk">
www.google.co.uk</a>

GitHub will render anything that starts https://, http:// or www. as a link.

Links are always displayed in blue rgb(009,105,218) #0969DA and underlined.

Links are always the same size as body text and can be emphasised with bold or italic by putting the appropriate number of asterisks before and after them (see section 6.4 and section 6.5). For example:

This is a link to **https://google.co.uk**.

This is a link to <strong><a href="https://www.google.co.uk">https://www.google.co.uk</a></strong>

⬆️ Top

It is possible to use substitute text which is displayed in place of the URL. Things like:

   The PracticalSeries website can be accessed here.

The word here is displayed in place of the full URL, but clicking the word navigates to the URL: https://practicalseries.com.

The Markdown for this is in the form:

The ${\large \color{#C00000}\text{Substitute\ Text}}$ can be anything at all (including spaces, emojis and any other character), the ${\large \color{#1F883D}\text{URL}}$ must be a proper URL. There is no space between the closing bracket and opening parenthesis: ${\large \color{#0050C0}\text{](}}$.

The Markdown for the above is:

The PracticalSeries website can be accessed [here](https://practicalseries.com).

The PracticalSeries website can be accessed <a href="https://practicalseries.com">
here</a>

A tooltip is a small box that opens up to display some information about the link whenever the mouse hovers over the link:

Try it by hovering the mouse over the link below:

   Search engine Google.

The following figure shows the effect:

Figure 9.2 — Link to a web page with substitute text and tooltip

The Markdown for this is in the form:

The ${\large \color{#C00000}\text{Substitute\ Text}}$ can be anything at all (including spaces, emojis and any other character), the ${\large \color{#1F883D}\text{URL}}$ must be a proper URL the ${\large \color{#ED7D31}\text{Tootltip\ Text}}$ can also be anything at all. There is no space between the closing bracket and opening parenthesis: ${\large \color{#0050C0}\text{](}}$. There must be at least one space between the end of the URL and the first quotation mark.

The Markdown for the above figure is:

Search engine [Google](https://Google.co.uk "Link to Google UK").

Search engine <a href="https://google.co.uk" title="Link to Google UK">Google</a>.

⬆️ Top

Linking to pages in the same Wiki doesn’t require a full web address (URL), GitHub accepts relative addresses^💠1 (this is true for both Markdown and HTML).

Let’s say that a Wiki exists with three pages in a folder structure as follows:

Figure 9.1 — Simple Wiki structure

Here there are three pages: Home.md in the root directory, Page01.md in folder 01_Page1 and Page02.md in folder 02_Page2. The .md files are shown in red in the above figure.

All Wiki pages are .md files and GitHub ignores the folder structure when navigating the Wiki folder structure for .md (but only for .md files, all other files must include the correct path to the file).

To link to any other page in the Wiki, all that is necessary is to include the filename, but not the extension in the link.

Thus if Page02.md required a link to Page01.md it would simply have the following Markdown:

[Link to page 1](page01)

<a href="page01">Link to page 1</a>

All that is needed for a link to any other page in the Wiki is simply the filename of the page that is to be navigated to (always without the file extension^💠2)

Links to other page in the Wiki can also have tooltips (in exactly the same way as links to an external page, see section 9.1.3 ), in this form:

For example adding a tooltip to the previous example gives (to see the effect, hover the mouse over the link at the bottom):

[Link to page 1](page01 "GO TO PAGE 1")

<a href="page01" title="GO TO PAGE 1">Link to page 1</a>

⬆️ Top

The Markdown and HTML forms for linking to a Wiki page are:

The ${\LARGE \color{#1F883D}\text{PageName}}$ in the both the Markdown link and the HTML link is the same as the name of the .md file with the following changes:

For example, the page:

    ${\LARGE \color{#446FBD}\text{08.02\ Block\ quotes,\ lists\ and\ alerts.md}}$

Would becomes the ${\LARGE \color{#1F883D}\text{PageName}}$:

    ${\LARGE \color{#1F883D}\text{08.02-block-quotes,-lists-and-alerts}}$

Thus:

[Section 8.2](08.02-block-quotes,-lists-and-alerts)

<a href="08.02-block-quotes,-lists-and-alerts">Section 8.2</a>

⬆️ Top

GitHub can link to any Markdown heading on a page (the ones constructed with leading hashes, see section 6.10 ). In fact, GitHub highlights the links and allows them to be copied, these highlights are the small chains that appear when the mouse hovers over the link:

Figure 9.3 — Heading link icon (highlighted)

To copy the link, right click and select ${\large \color{#00B050}\langle\text{Copy\ link}\rangle}$ from the drop down (note, this copies the full URL to the link). Left clicking the link will navigate to the heading (i.e. put the heading at the top of the browser page).

Clicking a link to a heading navigates up or down the page until the heading is at the top of the browser window.

Links to a heading on the same page are constructed in a similar way to the direct link using substitute text (see section 9.1.2) as follows:

The ${\large \color{#C00000}\text{Substitute\ Text}}$ can be anything you like; this is what is displayed as the link text.

⬆️ Top

The ${\large \color{#00B050}\text{headingName}}$ is the same as the heading itself with the following changes:

⬆️ Top

For example, on the Wiki page: 01 Introducing the GitHub Wiki there is a heading: 1.1. What are GitHub Wiki pages?.

The Markdown for the heading is this:

## 1.1&ensp;&emsp;&emsp;&ensp;&emsp13;&emsp13;&hairsp;<!-- H2 -->What are GitHub Wiki pages?

Now, this heading is a bit more complicated than the headings in section 6.10, but it works in the same way:

It starts as normal, with two hashes ##, it is a level 2 heading. There is a chapter and section number separated by a full stop 1.1.

Next, there are various special spacing characters:        , these are used to space the title text from the heading number (see section 7.2). This is followed by a comment field <!-- H2 --> that identifies the heading as a level 2 heading.

Finally, there is a question mark ? at the end.

The link to this heading (from within the same page), would be:

Link to [1.1 What are GitHub Wiki pages?](#11what-are-github-wiki-pages)

Link to <a href="#11what-are-github-wiki-pages">1.1 What are GitHub Wiki pages?</a>

Let’s examine what has happened to the heading link: ${\large \color{#1F883D}\text{11what-are-github-wiki-pages}}$ by applying the rules in the list in the previous section (List 9.3):

It is preceded by a single hash #, links only use one hash irrespective of the heading level.

The numbers 11 are the numbers in the heading 1.1 without the full stop (all non-alphanumeric characters are ignored).

All the special space characters   &c. are ignored as is the comment field.

Thus, the numbers are immediately followed by the text of the heading in lowercase.

All the spaces between the words in the heading text are replaced with dashes -.

Finally, the question mark at the end is missing (all non-alphanumeric characters are ignored).

So the Markdown (or HTML href ) for the link to the heading becomes:

#11what-are-github-wiki-pages

Tooltips can also be applied to links to headings, this is exactly the same as shown in section 9.1.3 (hover the mouse over the link at the bottom to see the tooltip):

Link to [1.1. What are GitHub Wiki pages?](#11what-are-github-wiki-pages "HEADING LINK")

Link to <a href="#11what-are-github-wiki-pages" title="HEADING LINK">1.1. What are GitHub Wiki pages?</a>

⬆️ Top

It is possible to link to any heading on a page within the same Wiki by adding the page name to the Markdown link. Links to a Hheading links to a point on a different page are constructed in a similar way to the heading link on a same page (see section 9.3), but also include the page name:

The ${\large \color{#C00000}\text{Substitute\ Text}}$ can be anything you like, this is displayed as the link text.

The rules for the ${\large \color{#4B0082}\text{pageName}}$ and ${\large \color{#1F883D}\text{headingName}}$ are given in section 9.2.1 and section 9.3.1.

⬆️ Top

Using the same example of section 9.3.2 where:

The Wiki page: 01 Introducing the GitHub Wiki has the heading: 1.1. What are GitHub Wiki pages?.

The Markdown for the heading is this:

## 1.1&ensp;&emsp;&emsp;&ensp;&emsp13;&emsp13;&hairsp;<!-- H2 -->What are GitHub Wiki pages?

This is the same as the heading in section 9.3.2.

The heading becomes the following when coverted to a link (again see section 9.3.2), the ${\large \color{#1F883D}\text{headingName}}$:

#11what-are-github-wiki-pages

The ${\large \color{#4B0082}\text{pageName}}$ (using the rules of section 9.2.1) becomes:

01-introducing-the-github-wiki

Thus the whole link become:

[1.1.What are GitHub Wiki pages?](01-introducing-the-github-wiki#11what-are-github-wiki-pages)

<a href="01-introducing-the-github-wiki#11what-are-github-wiki-pages">1.1 What are GitHub Wiki pages?</a>

⬆️ Top