09.05 Links - practicalseries/GitHub-Wiki-Design-and-Implementation GitHub Wiki

It is possible to link to any heading on a page (see section 9.3 and section 9.4). It is also possible to link to any other point on a page by including an anchor point.

Typically (and particularly with the Practical Series Wikis), this can be to link to a figure or table, or to link to the top and bottom of the page.

It is not possible to set these anchor points entirely within Markdown. HTML is required to establish the anchor point, once this is done, either Markdown or HTML can be used to navigate to it.

Anchor points are established by specifying a ${\large \color{#00B050}\text{name}}$ attribute for an HTML tag. Most HTML tags can have a ${\large \color{#00B050}\text{name}}$: <table> being the most common for Practical Series Wiki pages, but any tag will do (with the exception of the <img> tag for some reason).

This is done by simply adding the ${\large \color{#00B050}\text{name}}$ attribute to the opening tag:

<table name="idName">...</table>

<figure name="idName">...</figure>

It works for paragraph elements too:

<p name="idName">Any paragraph text</p>

To create an anchor point at some position on a Wiki page that does not have any existing HTML (say the top or bottom of the page), an empty <a> anchor tag is the best to use.

An empty anchor tag is simply a container to hold the ${\large \color{#00B050}\text{name}}$ tag. It looks like this:

<a name="idName"></a>

In all these examples, ${\large \color{#1F883D}\text{idName}}$ is a unique alphanumeric string (${\large \color{#1F883D}\text{idName}}$ must be unique within a page, there cannot be two ${\large \color{#00B050}\text{name}}$ attributes with the same name).

The Practical Series Wikis use ${\large \color{#1F883D}\text{idtop}}$ and ${\large \color{#1F883D}\text{idend}}$ to specify the top and bottom of the page respectively.

The empty anchor tag above does absolutely nothing on the Wiki page (it does not render as text or a link or manifest itself in any discernible way). It simply defines a point that can be navigated to.

To link to the anchor point, use the same Markdown or HTML links covered earlier in this section:

The substitute text can be anything you like (top of page, for example), the ${\large \color{#1F883D}\text{idName}}$ is the same name used in the anchor point and must be preceded by a single hash #.

The following example shows a link to the anchor point at the top of a page:

<a name="idtest"></a>

Lorem ipsum dolor sit amet, consectetur adipiscing elit. In consectetur tortor a tortor ornare,<br>
non pretium diam faucibus. Morbi ut mollis dolor, nec pretium tellus. Suspendisse ornare neque<br> 
placerat orci aliquam, eu sodales dui blandit. Maecenas nec risus vel magna blandit euismod.<br> 
Suspendisse id finibus purus. Nam ultricies non sapien ac rutrum

[Link to top of text](#idtest)

<a name="idtest"></a>

<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. In consectetur tortor a tortor ornare,<br>
non pretium diam faucibus. Morbi ut mollis dolor, nec pretium tellus. Suspendisse ornare neque <br>
placerat orci aliquam, eu sodales dui blandit. Maecenas nec risus vel magna blandit euismod.<br>
Suspendisse id finibus purus. Nam ultricies non sapien ac rutrum</p>

<a href="#idtest">Link to top of text</a>

⬆️ Top

If you’re wondering about the links to the top and bottom on the PracticalSeries Wiki pages, they look like this (highlighted in orange):

Figure 9.4 — PracticalSeries links to top and end of page

These use emojis (up and down arrows) to create the link.

The Markdown for the top and end of page links is:

**[:arrow_up: Top](#idtop)**

**[:arrow_down: End of page](#idend)**

<a href="#idtop"><strong>⬆ Top</strong></a>

<a href="#idend"><strong>⬇ End of page</strong></a>

In both these cases, the link is surrounded by double asterisks ** (<strong> in HTML), this is to put the link in bold.

The substitute text starts with either :arrow_up: or :arrow_down:, these are the emoji characters (⬆) and (⬇) respectively. The text that follows (Top or End of page) is simply the text that is displayed on the page following the arrow.

⬆️ Top

To link to an anchor point on another Wiki page, simply put the name of the page (with all spaces replaced by dashes before the ${\large \color{#4B0082}\text{pageName}}$${\large \color{#1F883D}\text{idName}}$):

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}}$ is given in section 9.2.1.

⬆️ Top

A link to download a file (rather than navigating to a web page) is possible (sort of) in both Markdown and HTML.

Generally, to download a file stored within a Wiki folder, all that is required is the full path to the file and the inclusion of the file extension.

For example, this Wiki has a zipx file that contains the HTML escape code list. It is stored in the Wiki folder /A-0000/04-data/html_escape_codes.zipx.

The full path to this file (as a URL is): https://github.com/practicalseries/GitHub-Wiki-Design-and-Implementation/wiki/A-0000/04-data/html_escape_codes.zipx

Entering this link in the address bar of a browser will cause it to download the file.

To download the file using Markdown, just use the standard Markdown link syntax:

In this case

[Click here to download the escape characters list](https://github.com/practicalseries/GitHub-Wiki-Design-and-Implementation/wiki/A-0000/04-data/html_escape_codes.zipx).

<a href="https://github.com/practicalseries/GitHub-Wiki-Design-and-Implementation/wiki/A-0000/04-data/html_escape_codes.zipx">Click here to download the escape characters list</a>

⬆️ Top

You may be wondering why the HTML link above didn’t use the ${\large \color{#00B050}\text{download}}$ attribute to force the file to download.

The normal HTML for downloading a file would be in the form

<a href="urlOfFile" download>Click here to download the file</a>

The download attribute forces the browser to download the file and not treat it as a link.

Unfortunately, the ${\large \color{#00B050}\text{download}}$ attribute is one of the attributes that is not permitted by GitHub, it is not whitelisted (see section 5.5.1).

This means that downloading a file depends to some extent on the browser being used. Some browsers are able to display certain files, and if they can, they will open a new tab and display the file. (for example linking to an image .png, .jpg &c. will almost certainly result in a new tab opening with the image being displayed).

If the browser does not recognise the file type or is unable to display it (compressed, ZIP, files almost always fall into this category), it will download it instead.

⬆️ Top

Spaces in filename are a bastard. It leads to endless confusion: sometimes it works if you leave the spaces in, sometime they have to be replaced with dashes -, sometimes with a plus + and sometimes with the URL code %20.

It’s a bugger.

Normal URLs, the ones you type into a web browser, do not have spaces in them.

Once you get past the top level domain .com, .co.uk &c. and into subdirectories, then file names can have spaces in them.

In terms of Wiki pages, we need the filenames for the page to have spaces in them. It is this filename that is used to display the main title for the page on the GitHub site.

This is the page ${\large \color{#446FBD}\text{01\ Introducing\ the\ GitHub\ Wiki}}$:

Figure 9.5 — Wiki page title

The title (at the top) is derived from the filename of the page, in this case it is:

   ${\large \color{#446FBD}\text{01\ Introducing\ the\ GitHub\ Wiki}}$

It has spaces in it.

We also want to be able to link to this page using Markdown and HTML from other pages within the Wiki, we may also want to link to it from external websites.

In all the previous examples in this section, where we have linked to other Wiki pages, the rules have been as follows:

The Wiki ${\large \color{#446FBD}\text{pageName}}$ used in the both the Markdown link and the HTML link is the same as the name of the .md file with the following changes:

The main point being: spaces are replaced with a dash -.

This works for GitHub Wikis (and other Markdown pages) because GitHub is creating the webpage itself from the Markdown that is supplied to it. In doing so, it is automatically replacing the spaces with dashes in the web address. GitHub also has control of any redirections that may occur when different formats are used for the space character.

In short, replacing spaces with dashes when accessing a Wiki page always works, but only for the page itself (the thing with the .md extension).

If an image were to be displayed and had the filename ${\large \color{#446FBD}\text{fig\ 99-01.png}}$ (i.e. a space between fig and the 99), and if the space were replaced with a dash (i.e. ${\large \color{#446FBD}\text{fig}\color{#C00000}\text{-}\color{#446FBD}\text{99-01.png}}$), then GitHub would not display it (it would not be able to find it).

To display or download any file (other than a Wiki page .md file) that has spaces in the name, the spaces must be replaced with ${\large \color{#C00000}\text{20}}$^💠3.

In fact the image above does exist, it is in the folder 99-0000/02-images of this Wiki.

This is the full link to it (it works if you paste it into a browser):

   https://github.com/practicalseries/GitHub-Wiki-Design-and-Implementation/wiki/99-0000/02-images/fig%2099-01.png

It’s a picture of my dog Henry:

Figure 9.6 — Henry

I’m pretty sure he’s smiling.

Interestingly, the ${\large \color{#C00000}\text{20}}$ thing also works for the Wiki pages (where we normally replace spaces with dashes). This is a link to the introductory page of this Wiki:

   ^{https://github.com/practicalseries/GitHub-Wiki-Design-and-Implementation/wiki/01-Introducing-the-GitHub-Wiki}

It also works if I replace the dashes in the page name with ${\large \color{#C00000}\text{20}}$:

   ^{https://github.com/practicalseries/GitHub-Wiki-Design-and-Implementation/wiki/01%20Introducing%20the%20GitHub%20Wiki}

⬆️ Top

This is a slightly esoteric point and I include it only for completeness (and to satisfy my own internal OCD-ness).

In all the above sections, when linking to another page in the Wiki, the .md extension has been removed from the Wiki page name in the URL. To access the ${\large \color{#446FBD}\text{01\ Introducing\ the\ GitHub\ Wiki.md}}$ page, the link is simply ${\large \color{#00B050}\text{01-Introducing-the-GitHub-Wiki}}$, no .md at the end (and spaces replace by dashes).

Now let’s say that instead of navigating to the page, you want to download it (or display the source Markdown, sometime referred to as the raw file, in a browser), then this is possible.

To do this, the full path to the file must be included (subdirectories &c.), the spaces in the filename replaced with ${\large \color{#C00000}\text{20}}$ and the .md extension must be included.

This is the link to the page above, it will open in a browser with the raw Markdown being displayed:

   ^{https://github.com/practicalseries/GitHub-Wiki-Design-and-Implementation/wiki/01-0000/01%20Introducing%20the%20GitHub%20Wiki.md}

It opens the raw Markdown for the file, the first part looks like this:

Figure 9.7 — The raw Markdown displayed in a browser

⬆️ Top

Reference style links are a bit of a peculiarity within Markdown (there is no HTML equivalent). I’m not sure many people use them; they are a bit confusing and the standard Markdown link format:

or

Are the most common types of links.

Reference style links (I’m just going to call them reference links) are intended as a way to make the text in a Markdown file clearer. Reference links have two parts, the first part, the reference, appears in-line with the text in the Markdown (in a paragraph for example), the second part, the URL, is somewhere else in the file (usually at the end) and contains the URL, this second part does not get displayed.

The first part, the reference, has the form:

Here, ${\large \color{#C00000}\text{Substitute\ Text}}$ can be anything you like, this is the text that is displayed on the page.

The ${\large \color{#1F883D}\text{Label}}$ is a unique alphanumeric identifier that links the reference to the URL in the second part below.

The second part, the URL, has the form:

The ${\large \color{#1F883D}\text{Label}}$ must match that in the first part, the ${\large \color{#4B0082}\text{URL}}$ is the URL of the link

Putting all this together in an example:

Developing the pumps was still not as hard as solving the second basic problem of rocket engines: 
making the propellants burn smoothly once they had reached the combustion chamber. 
The pumps brought the kerosene and the [LOX][lab01] to a circular metal slab three feet in 
diameter and about four inches thick, weighing 1,000 pounds, called the injector plate.

[lab01]:https://en.wikipedia.org/wiki/Liquid_oxygen

To add a tooltip, the second part becomes (there is a space between the end of the URL and the first quotaion mark):

Or in the above example:

Developing the pumps was still not as hard as solving the second basic problem of rocket engines: 
making the propellants burn smoothly once they had reached the combustion chamber. 
The pumps brought the kerosene and the [LOX][lab02] to a circular metal slab three feet in 
diameter and about four inches thick, weighing 1,000 pounds, called the injector plate.

[lab02]:https://en.wikipedia.org/wiki/Liquid_oxygen "Liquid Oxygen"

Some forms of Markdown put angle brackets around the URL, GitHub is tolerant of this too — this also works:

Developing the pumps was still not as hard as solving the second basic problem of rocket engines: 
making the propellants burn smoothly once they had reached the combustion chamber. 
The pumps brought the kerosene and the [LOX][lab03] to a circular metal slab three feet in 
diameter and about four inches thick, weighing 1,000 pounds, called the injector plate.

[lab03]:<https://en.wikipedia.org/wiki/Liquid_oxygen> "Liquid Oxygen"

⬆️ Top

This was discussed briefly in section 9.2, but is covered in more detail here.

When creating links to different elements in the same Wiki, it is possible to use relative links. This means that it is not necessary to enter the whole URL to link to a given element.

For example, consider the link to the picture of Henry in section 9.6.2, the full URL for this image was:

   https://github.com/practicalseries/GitHub-Wiki-Design-and-Implementation/wiki/99-0000/02-images/fig%2099-01.png

To access this image from any other page in the same Wiki, it is not necessary to use the full URL, all the pages in the given Wiki are in the subdirectory /wiki/ or in a subdirectory of a subdirectory.

This means that it is only necessary to include that part of the path from the current page to the image. If the image was to be displayed on the ${\large \color{#446FBD}\text{Home}}$ page for example, the link becomes:

[fig 99.01](./99-0000/02-images/fig%2099-01.png)

<a href="./99-0000/02-images/fig%2099-01.png"> fig 99.01</a>

The ./ at the start of the link is old school command line path terminology that means “the current directory”.

The other similar path commands are:

Strictly speaking, the ./ is not necessary and the link would work without it:

[fig 99.01](99-0000/02-images/fig%2099-01.png)

<a href="99-0000/02-images/fig%2099-01.png"> fig 99.01</a>

⬆️ Top

In the previous example, the link to ${\large \color{#446FBD}\text{fig\ 99-01.png}}$ from the ${\large \color{#446FBD}\text{Home}}$ was:

[fig 99.01](./99-0000/02-images/fig%2099-01.png)

<a href="./99-0000/02-images/fig%2099-01.png"> fig 99.01</a>

This makes perfect sense; the ${\large \color{#446FBD}\text{Home}}$ page is at the top level of the Wiki folder structure so all other elements are in some subdirectory relative to the ${\large \color{#446FBD}\text{Home}}$ page

Surprisingly, to link to the same image from a Wiki page that is stored in its own subdirectory, say ${\large \color{#446FBD}\text{01\ Introducing\ the\ GitHub\ Wiki.md}}$ which is in the subdirectory: /01-0000/, the link stays exactly the same:

[fig 99.01](./99-0000/02-images/fig%2099-01.png)

<a href="./99-0000/02-images/fig%2099-01.png"> fig 99.01</a>

It is surprising because the image is not in a subdirectory of the 01-0000 folder; to get to the 99-0000 folder from the 01-0000 folder we need to go up a level, i.e. the link should be:

[fig 99.01](../99-0000/02-images/fig%2099-01.png)

<a href="../99-0000/02-images/fig%2099-01.png"> fig 99.01</a>

With ../ at the start to go up a level.

So what is happening?

Well, GitHub has a flexible attitude when it comes to .md files (the Wiki pages).

With all Wiki pages (that end .md) GitHub ignores all subdirectories, it considers everything to be at the same top-level as the Home.md page.

The upshot of this is that when linking from a Wiki page to an element in the same Wiki, that page can be considered (for all practical purposes) to be in the top-level folder of the Wiki (i.e. at the /wiki/ folder level). All subfolders can thus be accessed using the ./ current directory path terminology.