09 Links

9Links

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:

	^{List 9.1 — Various types of links}
●	Link to an external web page (a web page that is not associated with a particular Wiki or repository)
●	Link to another page in the same Wiki
●	Link to headings on the current Wiki page
●	Link to headings on a different Wiki page
●	Link to a named element on the same Wiki page
●	Link to a named element on a different Wiki page
●	Download a file

All of these are covered in the next sections:

⬆️ Top

9.1Linking to an external web page

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

	^{List 9.2 — Links to an external web page}
❶	A straight forward (direct) link to a URL: https://google.co.uk
❷	A link to a URL using substitute text e.g. Google UK
❸	A link to a URL using substitute text and with a tooltip box that explains the link when the mouse hovers over it: e.g. Google UK

Taking each in turn:

⬆️ Top

9.1.1A direct link to a URL

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:

^{Markdown and GitHub output}
${\large \color{#0050C0}\text{M\ A\ R\ K\ D\ O\ W\ N}}$ 🔽	${\large \color{#B00000}\text{G\ I\ T\ H\ U\ B}\space\ \space\text{O\ U\ T\ P\ U\ T}}$ 🔽
This is a link to https://google.co.uk.	This is a link to https://google.co.uk.
This is a link to https://www.google.co.uk.	This is a link to https://www.google.co.uk.
This is a link to www.google.co.uk.	This is a link to www.google.co.uk.
^{Table 9.1 — Markdown for a basic link}

The equivalent HTML for the above is:

^{HTML and GitHub output}
${\large \color{#00C050}\text{H\ T\ M\ L}}$ 🔽	${\large \color{#B00000}\text{G\ I\ T\ H\ U\ B}\space\ \space\text{O\ U\ T\ P\ U\ T}}$ 🔽
This is a link to <a href="https://google.co.uk"> https://google.co.uk</a>	This is a link to https://google.co.uk
This is a link to <a href="https://www.google.co.uk"> https://www.google.co.uk</a>	This is a link to https://www.google.co.uk
This is a link to <a href="www.google.co.uk"> www.google.co.uk</a>	This is a link to www.google.co.uk
^{Table 9.2 — HTML for a basic link}

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

Note

GitHub does not check the format of the link beyond the starting characters, it would think www.google was a perfectly good link (even though the domain suffix is missing), it would also think https://🌳🌳🌳🌳 is a link despite the fact the characters in it are not valid for URLs.

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:

^{Markdown, HTML equivalence and GitHub output}
${\large \color{#0050C0}\text{M\ A\ R\ K\ D\ O\ W\ N}}$ 🔽
This is a link to https://google.co.uk.
${\large \color{#00C050}\text{H\ T\ M\ L}}$ 🔽
This is a link to <strong><a href="https://www.google.co.uk">https://www.google.co.uk</a></strong>
${\large \color{#B00000}\text{G\ I\ T\ H\ U\ B}\space\ \space\text{O\ U\ T\ P\ U\ T}}$ 🔽
This is a link to https://google.co.uk.
^{Table 9.3 — A basic link in bold}

⬆️ Top

9.1.2A link using substitute text

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:

${\LARGE \color{#0050C0}\text{[}\color{#C00000}\text{Substitute\ Text}\color{#0050C0}\text{](}\color{#1F883D}\text{URL}\color{#0050C0}\text{)}}$

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:

^{Markdown, HTML equivalence and GitHub output}
${\large \color{#0050C0}\text{M\ A\ R\ K\ D\ O\ W\ N}}$ 🔽
The PracticalSeries website can be accessed [here](https://practicalseries.com).
${\large \color{#00C050}\text{H\ T\ M\ L}}$ 🔽
The PracticalSeries website can be accessed <a href="https://practicalseries.com"> here</a>
${\large \color{#B00000}\text{G\ I\ T\ H\ U\ B}\space\ \space\text{O\ U\ T\ P\ U\ T}}$ 🔽
The PracticalSeries website can be accessed here.
^{Table 9.4 — A basic link with substitute text}

9.1.3A link using substitute text with tooltip

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:

${\LARGE \color{#0050C0}\text{[}\color{#C00000}\text{Substitute\ Text}\color{#0050C0}\text{](}\color{#1F883D}\text{URL}\color{#0050C0}\text{\ "}\color{#ED7D31}\text{Tooltip\ Text}\color{#0050C0}\text{")}}$

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:

^{Markdown, HTML equivalence and GitHub output}
${\large \color{#0050C0}\text{M\ A\ R\ K\ D\ O\ W\ N}}$ 🔽
Search engine [Google](https://Google.co.uk "Link to Google UK").
${\large \color{#00C050}\text{H\ T\ M\ L}}$ 🔽
Search engine <a href="https://google.co.uk" title="Link to Google UK">Google</a>.
${\large \color{#B00000}\text{G\ I\ T\ H\ U\ B}\space\ \space\text{O\ U\ T\ P\ U\ T}}$ 🔽
Search engine Google.
^{Table 9.5 — A basic link with substitute text and tooltip}

⬆️ Top

9.2Linking to another page in the same Wiki

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:

^{Markdown, HTML equivalence and GitHub output}
${\large \color{#0050C0}\text{M\ A\ R\ K\ D\ O\ W\ N}}$ 🔽
[Link to page 1](page01)
${\large \color{#00C050}\text{H\ T\ M\ L}}$ 🔽
<a href="page01">Link to page 1</a>
${\large \color{#B00000}\text{G\ I\ T\ H\ U\ B}\space\ \space\text{O\ U\ T\ P\ U\ T}}$ 🔽
Link to page 1
^{Table 9.6 — Relative link to a page within the same Wiki}

Note

The important thing to remember is that the .md extension must not be included in the relative link. Only use the filename that precedes the extension (it is not case sensitive).

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:

${\LARGE \color{#0050C0}\text{[}\color{#C00000}\text{Substitute\ Text}\color{#0050C0}\text{](}\color{#1F883D}\text{PageName}\color{#0050C0}\text{\ "}\color{#ED7D31}\text{Tooltip\ Text}\color{#0050C0}\text{")}}$

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

^{Markdown, HTML equivalence and GitHub output}
${\large \color{#0050C0}\text{M\ A\ R\ K\ D\ O\ W\ N}}$ 🔽
[Link to page 1](page01 "GO TO PAGE 1")
${\large \color{#00C050}\text{H\ T\ M\ L}}$ 🔽
<a href="page01" title="GO TO PAGE 1">Link to page 1</a>
${\large \color{#B00000}\text{G\ I\ T\ H\ U\ B}\space\ \space\text{O\ U\ T\ P\ U\ T}}$ 🔽
Link to page 1
^{Table 9.7 — Relative link to a page within the same Wiki with tooltip}

⬆️ Top

9.2.1Rules for linking to a Wiki page

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

${\LARGE \color{#0050C0}\text{[}\color{#C00000}\text{Substitute\ Text}\color{#0050C0}\text{](}\color{#1F883D}\text{PageName}\color{#0050C0}\text{\ "}\color{#ED7D31}\text{Tooltip\ Text}\color{#0050C0}\text{")}}$ ${\LARGE \color{#0050C0}\text{<a href="}\color{#1F883D}\text{PageName}\color{#0050C0}\text{" title="}\color{#0050C0}\text{\ "}\color{#ED7D31}\text{Tooltip\ Text}\color{#0050C0}\text{">)}\color{#C00000}\text{Substitute\ Text}\color{#0050C0}\text{</}\text{a>}}$

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:

	^{List 9.3 — RRules for converting a page name to a link}
❶	Do not add the `.md` extension to the ${\LARGE \color{#1F883D}\text{PageName}}$
❷	Any spaces within the ${\LARGE \color{#1F883D}\text{PageName}}$ are replaced with a dash `-`
❸	All uppercase letters are made lowercase (optional)

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:

^{Markdown, HTML equivalence and GitHub output}
${\large \color{#0050C0}\text{M\ A\ R\ K\ D\ O\ W\ N}}$ 🔽
[Section 8.2](08.02-block-quotes,-lists-and-alerts)
${\large \color{#00C050}\text{H\ T\ M\ L}}$ 🔽
<a href="08.02-block-quotes,-lists-and-alerts">Section 8.2</a>
${\large \color{#B00000}\text{G\ I\ T\ H\ U\ B}\space\ \space\text{O\ U\ T\ P\ U\ T}}$ 🔽
Section 8.2

Note

While it is not necessary to change the name to all lowercase letters, it is best to do so, it gives consistency to the addressing.

⬆️ Top

9.3Linking to headings on the current page

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.

Note

Just inserting the hash and the #headingName directly in the Markdown (like the direct link of section 9.1.1) will not work.

⬆️ Top

9.3.1Rules for converting a heading to a link

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

	^{List 9.4 — Rules for converting a heading}
❶	There is only one hash `#` before the ${\large \color{#00B050}\text{headingName}}$ irrespective of the heading level
❷	All text is converted to lowercase
❸	Spaces are converted to a single dash
❹	If multiple consecutive spaces are present, they are converted to a single dash
❺	Special space characters (see section 7.2) are ignored
❻	Any HTML tags are ignored (tags and attributes between `<>`)
❼	Any comments within the heading (text between ``) are ignored
❽	Numbers (0 to 9) are included
❾	All non-alphanumeric characters are ignored

⬆️ Top

9.3.2An example of a heading link

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:

^{Markdown and GitHub output}
${\large \color{#0050C0}\text{M\ A\ R\ K\ D\ O\ W\ N}}$ 🔽
## 1.1&ensp;&emsp;&emsp;&ensp;&emsp13;&emsp13;&hairsp;<!-- H2 -->What are GitHub Wiki pages?
${\large \color{#B00000}\text{G\ I\ T\ H\ U\ B}\space\ \space\text{O\ U\ T\ P\ U\ T}}$ 🔽
1.1 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: &ensp;&emsp;&emsp;&ensp;&emsp13;&emsp13;&hairsp;, these are used to space the title text from the heading number (see section 7.2). This is followed by a comment field  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:

^{Markdown, HTML equivalence and GitHub output}
${\large \color{#0050C0}\text{M\ A\ R\ K\ D\ O\ W\ N}}$ 🔽
Link to [1.1 What are GitHub Wiki pages?](#11what-are-github-wiki-pages)
${\large \color{#00C050}\text{H\ T\ M\ L}}$ 🔽
Link to <a href="#11what-are-github-wiki-pages">1.1 What are GitHub Wiki pages?</a>
${\large \color{#B00000}\text{G\ I\ T\ H\ U\ B}\space\ \space\text{O\ U\ T\ P\ U\ T}}$ 🔽
Link to 1.1 What are GitHub Wiki pages?
^{Table 9.8 — A link to a heading on the same page}

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 &emsp; &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:

^Markdown
${\large \color{#0050C0}\text{M\ A\ R\ K\ D\ O\ W\ N}}$ 🔽
#11what-are-github-wiki-pages

9.3.3Heading link with tooltips

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):

^{Markdown, HTML equivalence and GitHub output}
${\large \color{#0050C0}\text{M\ A\ R\ K\ D\ O\ W\ N}}$ 🔽
Link to [1.1. What are GitHub Wiki pages?](#11what-are-github-wiki-pages "HEADING LINK")
${\large \color{#00C050}\text{H\ T\ M\ L}}$ 🔽
Link to <a href="#11what-are-github-wiki-pages" title="HEADING LINK">1.1. What are GitHub Wiki pages?</a>
${\large \color{#B00000}\text{G\ I\ T\ H\ U\ B}\space\ \space\text{O\ U\ T\ P\ U\ T}}$ 🔽
Link to 1.1. What are GitHub Wiki pages?
^{Table 9.9 — A link to a heading on the same page with tooltips}

⬆️ Top

9.4Linking to headings on a different page

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:

${\LARGE \color{#0050C0}\text{[}\color{#C00000}\text{Substitute\ Text}\color{#0050C0}\text{](}\color{#4B0082}\text{pageName}}$${\LARGE \color{#1F883D}\text{headingName}\color{#0050C0}\text{)}}$

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

9.4.1An example of a heading link

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:

^{Markdown and GitHub output}
${\large \color{#0050C0}\text{M\ A\ R\ K\ D\ O\ W\ N}}$ 🔽
## 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}}$:

^Markdown
${\large \color{#0050C0}\text{M\ A\ R\ K\ D\ O\ W\ N}}$ 🔽
#11what-are-github-wiki-pages

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

^Markdown
${\large \color{#0050C0}\text{M\ A\ R\ K\ D\ O\ W\ N}}$ 🔽
01-introducing-the-github-wiki

Thus the whole link become:

^{Markdown, HTML equivalence and GitHub output}
${\large \color{#0050C0}\text{M\ A\ R\ K\ D\ O\ W\ N}}$ 🔽
[1.1.What are GitHub Wiki pages?](01-introducing-the-github-wiki#11what-are-github-wiki-pages)
${\large \color{#00C050}\text{H\ T\ M\ L}}$ 🔽
<a href="01-introducing-the-github-wiki#11what-are-github-wiki-pages">1.1 What are GitHub Wiki pages?</a>
${\large \color{#B00000}\text{G\ I\ T\ H\ U\ B}\space\ \space\text{O\ U\ T\ P\ U\ T}}$ 🔽
1.1 What are GitHub Wiki pages?
^{Table 9.10 — A link to a heading on a different page}

⬆️ Top

Footnotes:

Note

^💠1 A relative address, or relative file path, identifies the location of a file relative to the location of the current page. It is common practice for websites to use relative addressing (see section 9.8 for details).↩

Note

^💠2 The relative link must not include the file extension, if the link in the example were page01.md, the link would not work, GitHub will not find the file (I think it adds .md to the filename and is now trying to find a file that ends .md.md and it can’t).↩