A Markdown-powered wiki – an introduction to Markdown

While GitHub supports multiple markup languages, we will explore Markdown as it is the most well-known one.

Let's create another page, named Installation, with some content as follows:

I have used several Markdown elements and hitting Preview will show you how the page will be rendered when it is saved. After you hit the Save Page button, the new Installation page will look like the following:

Some elements worth mentioning are the links. There are two kinds of links: external and internal. External ones are written by giving the full URL including the FQDN, whereas internal links only get called with the page name.

You can have external links that display the actual URL by surrounding them with <>, such as <https://duckduckgo.com>, and you can also include some random text such as [git clone](https://git-scm.com/docs/git-clone). Inside the brackets, you can add any text you want, followed by the actual link inside parentheses. Be careful to not leave any spaces between the second bracket and the first parenthesis.

Internal links are useful when you want to link to another page of your wiki. Imagine you have 42 pages and you have to type the whole URL whenever you want to refer to another page. GitHub implements MediaWiki's markup in that case. Use double brackets ([[]]), and inside them, put the name of the wiki page you want to link to. In our example, I used [[Contributing]] and this will create a link to another page. Notice that if the link does not exist, it is rendered in red. If you click on it, you will be redirected to create the page.

When creating headers, you use # before the text. The number of # defines the header style that will be used. Each header gets a separate anchor link, which you can see if you place your mouse over it on a saved page. This anchor link can then be used to reference internal links.

In our example, you can see that I created three headers, namely  Getting started, Contribute, and Alternative methods. In Getting started, I placed an interlink with a reference to Alternative methods. The piece of Markdown that did this is [[here|Installation#alternative-methods]]. This style introduces two new areas to explore.

Firstly, you can see that an alternate text can be used much like with external links. The only difference is that both the alternate text and the link are placed inside the double brackets separated by a pipe (|). Secondly, you can see how the call to the internal reference link is made. The page title goes first followed by the octothorp sign (#) and last is the header. It is important to understand that the header, as part of the interlink, gets transformed, whereas empty spaces are replaced with hyphens (-) and all special characters (?,'!, and so on) are lost.

You can always use the preview to test whether an anchor link will be rendered correctly.

We have only scratched the surface regarding Markdown. You can read more about it in the nice cheat sheet at https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet.