90 How to build a GitHub Wiki

90. How to build a GitHub Wiki

This page originally started life as a template page, a set of examples that I could quickly access and copy to the more relevant Wiki pages in this repository.

In doing so, I realised that there are various techniques (some might call them hacks) to get around the limitations of GitHub flavoured markdown (GFM), I also realised that while many features of the Wiki are documented by GitHub:

The GitHub documentation

https://docs.github.com/en/enterprise-cloud@latest

Select Get started and then Writing on GitHub.

There is also a style guide for GitHub documents (this is GitHub’s own style guide for its own documentation), and it has some useful tips and conventions:

https://docs.github.com/en/contributing

The explanations don’t always cover everything (or at least the explanations can be hard to find).

The upshot of all this is that what started as a simple template page has become a bit of a tutorial for producing GitHub Wiki files. I hope you find it useful.

The explanations in the GitHub documentation don’t always cover everything (or at least the explanations can be hard to find) and you end up looking around all sorts of websites to find the information.

The upshot of all this is that what started as a simple template page has become a bit of a tutorial for producing GitHub Wiki files. I hope you find it useful.

⬆️ Top

90.1. What are GitHub Wiki pages?

GitHub Wikis (as they are called) are simply a set of pages where the documentation for a repository can be stored.

GitHub Wiki pages are constructed using the same markdown language used in readme.md files (more or less, there are some minor differences¹)

Every repository in GitHub can have Wiki pages, it’s a built-in function of GitHub. The Wiki option appears in the top bar of the repository, point 1 in the figure below:

Note

¹ I’m not sure why there are differences, it seems a bit arbitrary. The main difference is that the [^1]: footnote format available in readme.md files is not supported in Wikis. I will document the differences as I find them in the template section of this Wiki.


Figure 90.1 — Accessing a Wiki

Wiki pages are enabled for a new repository by default, but can be disabled if required.

To disable the Wiki option for a repository, click Settings (point 2 in the figure above), select General in the left-hand menu bar and then in the Features area (main section) untick the Wikis box:


Figure 90.2 — Disabling a Wiki

Note

Disabling a Wiki does not delete it, it simply stops it being accessed. Re-enabling a disabled Wiki will put it back just as it was (it is even possible to push changes to a disabled Wiki from a local repository).

⬆️ Top

90.2. Understanding the Wiki pages

The way the Wiki pages work and the way they link to a repository takes a bit of getting used to. In its simplest form a GitHub Wiki document is just a markdown file (just like readme.md) that lives in a separate area of a GitHub repository. In practice (and this can be slightly hard to grasp) it doesn’t actually get stored in the main repository (although it has the same start to its URL). For example, the readme.md file in the PS2001-PAL Software repository has the following URL:

https://github.com/practicalseries/PS2001-pal-software/blob/master/README.md

The home (landing) page for the Wiki documents for the same repository is:

https://github.com/practicalseries/PS2001-pal-software/wiki

They both start with https://github.com/practicalseries/PS2001-pal-software/ but the main repository is in the folder /blob/, the Wiki files are under a different folder /wiki/. This wiki folder is completely separate to the main folder.

If you were to pull the PS2001 PAL software repository to a local machine, the Wiki files would not be present within the local repository.

The Wiki pages are in fact a repository in their own right, they are associated with the main repository (PS2001-pal-software in this case) but are not part of it.

⬆️ Top

90.3. Creating a Wiki for a repository

This bit is easy, in the main repository, click the Wiki link at the top:


Figure 90.3 — Creating a Wiki

This opens the create first page screen:


Figure 90.4 — Create the first page

Click Create the first page button:

This creates the main page of the Wiki; this page is always called Home (it’s actually called Home.md):


Figure 90.5 — Home page

The important thing to note here is the Edit mode: this is automatically set to Markdown which is usually the best options. The other choices are:

AcsiiDoc
Creole
MediaWiki
Org-mode
Pod
RDoc
Textile
reStructuredText

I’m not sure if any of these are better than Markdown (they all seem to do the same things in different ways, see here https://hyperpolyglot.org/lightweight-markup) I’ve not had time to learn them all, from what I’ve seen on Google, AsciiDoc perhaps has more flexibility, but seems hard to use.

For the purpose of everything in this document, I’m using Markdown.

To create the page, click Save page and that’s it, clicking the Wiki link on the top line of the repository will show the new Home page:


Figure 90.6 — The newly created Wiki

⬆️ Top

90.4. Cloning a Wiki to a local machine

The Wiki repository can be opened locally on a machine using the “clone this wiki locally” link on any Wiki page, clicking the link copies the wiki link to the clipboard, in this case it is:

https://github.com/practicalseries/PS2001-pal-software.wiki.git

To make a local copy of this repository using VS Code:

open a new VS Code window and do the following:
Select Source Control (in the left bar), Ctrl+Shift+G
Select Clone Repository
Paste the link above into the editor as shown below:


Figure 90.7 — Clone a local copy of a Wiki

Hit enter and when prompted select open the repository, the PS2001 PAL Software Wiki looks like this:


Figure 90.8 — A local copy of the Wiki

This is now a cloned copy of the Wiki on a local machine.

- [90. How to build a GitHub Wiki](#90how-to-build-a-github-wiki) - [90.1. What are GitHub Wiki pages?](#901what-are-github-wiki-pages) - [90.2. Understanding the Wiki pages](#902understanding-the-wiki-pages) - [90.3. Creating a Wiki for a repository](#903creating-a-wiki-for-a-repository) - [90.4. Cloning a Wiki to a local machine](#904cloning-a-wiki-to-a-local-machine)