01 Introducing the GitHub Wiki - practicalseries/GitHub-Wiki-Design-and-Implementation GitHub Wiki
GitHub introduced Wikis in 2008 and they are available to every repository on GitHub (both public and private) and are accessed by clicking the Wiki button in the main navigation bar of the repository:
|
| Figure 1.1 — Accessing a Wiki |
|---|
GitHub Wikis are individual to each repository and are designed to host the detailed documentation for that repository. The idea being that the documentation that lives in the repository (usually the README.md file) is generally used as a short introduction to the repository, explaining the purpose of the repository and providing a quick guide to how it should be used, what its requirements are and other basic information.
Or, as GitHub put it:
It would certainly be possible to fully document a repository by adding further document files into the repository itself (there is nothing to stop you doing so), a repository will accommodate as many Markdown files (.md files) as you like. It is not, however, good practice to do this.
By keeping the full documentation files within the repository, it means that every change to the documentation becomes a change to the repository itself (with all the required commits and comments). If the documentation is extensive (it may for example be an instruction manual or complete tutorial for the software within the project), and was contained within the main repository, there could be as many commits and branches for the documentation as there are for the software project itself.
It is better to keep the project documentation separate from the repository software. By doing so, changes to the software within the main repository and the maintenance of the documentation associated with the repository do not interfere with each other.
This is the purpose of the GitHub Wiki. The Wiki is attached to a particular repository, but changes to the Wiki do not add commits or changes to the repository itself.
Think of the Wiki as a document package (a set of pages) that accompany a particular repository.
GitHub Wikis 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💠1).
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:
|
| Figure 1.2 — Accessing a Wiki and its settings |
|---|
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
|
| Figure 1.3 — Disabling a Wiki |
|---|
The second option here determines who can modify the Wiki. By default this is restricted to those users that are able to push changes to the main repository.
Unticking this box is not recommended and allows anyone to edit and change the Wiki.
Important
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).
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 clone (“fork” in GitHub terminology) 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.
This bit is easy. To create a Wiki for a repository, all that is necessary is to create the first page (I actually think the structure for the Wiki is created when the main repository is created, it just doesn’t have any pages in it).
To create the Wiki, just create the first page (below):
In the main repository, click the
|
| Figure 1.4 — Creating a Wiki |
|---|
This opens the create first page screen:
|
| Figure 1.5 — Create the first page |
|---|
Click
This creates the main page of the Wiki; this page is always called Home (it’s actually called Home.md):
|
| Figure 1.6 — Add content to the first page |
|---|
The important thing to note here is the Markdown which is usually the best options.
The other choices are:
|
| List 1.1 — Edit modes for a Wiki page |
|---|
Note
I’m not sure if any of these are better than Markdown (they all seem to do the same things in different ways. The following site provides a fairly good summary of the differences: https://hyperpolyglot.org/lightweight-markup). From the little I have read, it seems AsciiDoc is the best alternative, its syntax is similar to Markdown, but it offers more features and flexibility.
For the purpose of everything in this document, I’m using Markdown. The reason for this is that everyone who has created a repository will have used Markdown (it’s the same language used for all those README.md files) and will have some familiarity with it. It also means that sections of the Wiki can be directly cut and pasted into repository .md files without modification.
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 1.7 — The newly created Wiki Home page |
|---|
Once a Wiki has been created (the
|
| Figure 1.8 — Create a new Wiki Page |
|---|
The first thing to enter is a name for the page (this can be anything), enter it where it says 01 Introduction.
The two tabs
When the content has been entered and previewed, the page can be saved by pressing the green
The final thing looks like this:
|
| Figure 1.9 — A new Wiki Page editor |
|---|
It renders like this:
|
| Figure 1.10 — The new Wiki Page |
|---|
Editing a Wiki page is exactly the same process, just click the
|
| Figure 1.11 — Edit a Wiki Page |
|---|
The only differences being the options to
Again, if changes are made, the changes are made permanent by clicking the
As before, the Updated 01 Introduction).
It’s as well to get this out of the way — it’s confusing.
Although nothing suggests this, the Wiki pages are in fact a repository in their own right. It does not form part of the main project repository and it does not use the same terminology (it says “Save” instead of “Commit”), but it is, nonetheless, a fully-fledged repository.
If the Wiki pages were cloned to a local machine (see section 2), it would have a .git folder that stores all the commit information and respective versions. This is just like any other GitHub repository.
Every time a Wiki page is modified and “saved”, it is just the same as modifying a file in a standard repository and “committing” the changes.
This is the reason that we can view the history of a particular page in the repository.
Despite the fact that the Wiki is a repository, GitHub does not exactly treat it as such. GitHub will ignore any branches within a Wiki (unlike a standard repository) and it does not have the same ability to tag commits or even view the full commit history.
GitHub will allow the history of a particular page to be viewed though:
To view the history of a particular page, select the page in the Wiki and click
|
| Figure 1.12 — Wiki page history |
|---|
The number on the right is the 7-digit SHA (hash) commit number (just like a normal repository).
Ticking any two of the tick boxes and selecting
|
| Figure 1.13 — Version differences within a file |
|---|
Note
Unlike a standard repository, it is not possible (from within GitHub) to see all the commits for all pages in one place. For a standard repository, clicking where it says
Once a Wiki is cloned to a local machine (see section 2) and opened in a text editor (VS Code is the editor of choice) it can be viewed like any other repository and all commits can be seen.
This is easy. It doesn’t.
GitHub will only ever display Wiki content that is on the Master branch. All other branches are ignored and cannot be accessed via GitHub.
The confusion continues.
Let’s say that I logon to GitHub using the username: practicalseries and let’s say I now create a repository called TestRepo, like this:
|
| Figure 1.14 — A test repository |
|---|
It looks like this:
|
| Figure 1.15 — The new test repository |
|---|
Now let’s add a new Wiki (
The next thing is to access a page in the main repository and also a page in the Wiki.
Firstly, lets access the README.md file (by clicking on it in the file list, highlighted above), it will open in the browser window (this time I.ve shown the whole browser window):
|
| Figure 1.16 — URL for a standard REPOSITORY page |
|---|
The URL the browser is looking at is:
https://github.com/practicalseries/TestRepo/blob/master/README.md
This is a standard format for every repository, it is made up as follows:
The important thing here is (the surprisingly named)
If we do the same with the Wiki Home page (by clicking the
|
| Figure 1.17 — URL for a WIKI page |
|---|
This time the URL the browser is looking at is:
The URL the browser is looking at is:
https://github.com/practicalseries/TestRepo/wiki
This is a standard format for every repository, it is made up as follows:
The important thing here is the
Comparing these two URLs:
The first bit is the same for both, they both start:
It means that within the GitHub website the two are both stored under a particular username and are also stored in the same repository. They are linked together.
The difference is that the main repository is then stored under the directory
If I clone the main repository to a local machine, the local repository contains everything inside the
If I clone the Wiki to a local machine, the local repository contains everything inside the
Thus the main repository and the Wiki are in the same project defined by:
But they diverge into different
Hence the main repository and the Wiki repository are independent of each other, but both are stored in the same parent GitHub project:
In the case of this example project it is:
I apologise for the convoluted explanation and I hope that it describes things sufficiently well for you to understand it. It is not the most obvious of arrangements.
GitHub Wiki pages have various standard (and in some cases, optional) components. These can be seen by examining a PAL Software Wiki page as it currently appears (below):
|
| Figure 1.18 — The PAL Software Wiki page |
|---|
The GitHub Wiki pages are all hosted by GitHub itself and GitHub applies a certain structure to the page: Title, revision information, Contents (pages) list, sidebar and footer.
Taking them in order:
At the top left is the title of the particular page (point ① in the Figure 1.18, Home in this case). The title is always the name of the .md file containing the content of the page (in this case the file is called Home.md and the page title is thus
Beneath the title is the revision information (point ② in the Figure 1.18), this again is generated by GitHub. It shows the username of the last person to edit the page, when the page was edited and how many revisions of the particular page exist.
Clicking the number of revisions (
The third point (point ③ in Figure 1.18) is the Contents or Pages area, this contains a list of all the pages present in the Wiki. Clicking the little arrow on the left will expand the page and list all the headings within it, for the PAL Software Wiki it looks like this:
|
| Figure 1.19 — The Wiki contents page |
|---|
When expanded, the headings within a page are shown in black (it irritates me the way these headings break across lines).
I’ll say right from the start I’m not a fan of the default Contents area and I don’t use it. It would be nice if there was a way to turn it off.
I can see what GitHub is doing, it is making sure that all the pages in the Wiki are accessible, the problem I have is the way it does it:
The order of the pages in the Pages area is always listed in alphanumeric order.
Let’s say that a Wiki numbers its pages by Chapter and Section and has multiple instances of each, then the following pages:
And
Would appear in the Pages area as:
|
| Figure 1.20 — Pages listed in the wrong order |
|---|
I.e. the
It’s even worse if there are no section numbers and the pages are just given a title. Under these circumstances the pages will appear in alphabetical order and this is probably not the order that is required.
This is covered in more detail in section 3.3, but for the sake of completeness I summarise it here.
The best way to get around the problem is to give pages a numbering structure, let’s say Chapter, Section and Division, each being a two-digit number with leading zeros.
This can be seen in the following example:
|
| Figure 1.21 — Pages listed in the right order |
|---|
The key is to always use leading zeros. This arrangement always works.
Section 3.3 explains this in more detail with the inclusion of a folder structure and full numbering arrangements.
The sidebar is an optional component and is a common area to the top-right of all Wiki document pages (point ④ in Figure 1.18).
The sidebar is user configurable (you can put what you like in it), but is generally used to hold a user configured contents area. The sidebar is always narrow and uses a smaller text size than the main area of the Wiki page, it about a third of the width of the main text area.
Sidebars created with GitHub are common to all pages, the same sidebar, once created will appear on every Wiki page. section 4 explains how to have different sidebars for each page.
By default, there is no sidebar (see section 1.6.1 for how to create a basic GitHub sidebar).
The footer is another optional component and appears as a common area at the bottom of all Wiki document pages (point ⑤ in Figure 1.18).
The footer is user configurable (you can put what you like in it), but is generally used to hold copyright and colophonic information. The footer is the same width as the main text area. Footers created with GitHub are common to all pages, the same footer, once created will appear on every Wiki page. section 4 explains how to have different footers for each page.
By default, there is no footer (see section 1.6.1 for how to create a basic GitHub footer).
The sidebar and footer are optional components of the GitHub Wiki and are configurable by the user.
In Figure 1.18, the sidebar (point ④) is located in the top-right area below the GitHub generated Contents/pages section. The footer is at the bottom of the page (point ⑤).
When you create a sidebar or footer (see below), that sidebar will appear on every page in the Wiki.
GitHub, I think, intends the sidebar to hold a custom navigation list that allows the user to specify the order in which pages appear &c. The footer is intended to hold common information such as a colophon, copyright and licence message.
GitHub intends the sidebar and footer to be simple elements that are common to all pages.
This approach may be fine for GitHub, but the PAL Software Wiki needs something a bit more advanced. The navigation tables shown in Figure 1.18 above (with the arrows and home symbol) take the user to previous or next chapters and pages, consequently, these have to be adaptable from one page to the next and this requires each page to have unique (ish) sidebars and footers.
It is possible to have separate sidebars and footers on each page, however GitHub does not explain how to do it. This document contains a full description of how to have different sidebars and footers for each Wiki page, it is explained fully in section 4.
First of all let’s examine what GitHub intended with a sidebar and a footer:
If no sidebar or footer exists, GitHub will prompt for them to be made on the Home page. Clicking either option will open the editor and allow entries to be made.
|
| Figure 1.22 — Creating a sidebar or footer |
|---|
Sidebars and footers that already exist can be edited from any page by clicking the pencil symbols at the top right of each area (highlighted below for the sidebar):
|
| Figure 1.23 — Editing a sidebar or footer |
|---|
Creating a sidebar or footer using this method creates common sidebars and footers that are visible on every page of the Wiki. section 4 explains how to create individual sidebar and footer areas for each page.
Footnotes:
Note
💠1 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 document the differences I find in section 5.6.↩
|
|
|
|
|
|
The PracticalSeries of Publications — Copyright © 2025 Michael Gledhill
⬆️ Top | [email protected] | PracticalSeries of Publications | Main repository