90.05 Basic components of a Wiki

90.5. Basic components of a Wiki

GitHub Wiki pages have various standard (and in some cases, optional) components. These can be seen by examining the PAL Software Wiki home page as it currently appears (below):


Figure 90.9 — The PAL Software Wiki home page

The GitHub Wiki pages are all hosted and constructed 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:

⬆️ Top

90.5.1 Title bar and revision

At the top left is the title of the particular page (point 1 in the above image, 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 “Home”).

Beneath the title is the revision information (point 2 in the above image), this again is generated by GitHub. It shows the user name 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 (2 revisions in this case), will take you to the History page and list all the changes that have been made to the particular Wiki page (remember the Wiki is a repository in its own right).

⬆️ Top

90.5.2 Contents area

The third point (point 3 in Figure 90.9) is the Contents or Pages area, this contains a list of all the pages present in the Wiki. Clicking the little arrow will expand the area, for the PAL Software Wiki it looks like this:


Figure 90.10 — 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 listed in alphanumeric order (based on the ASCII table https://www.ascii-code.com/).

Let’s say that a Wiki numbers its pages by Chapter and Section and has multiple instances of each. if pages were numbered directly with Chapter, Section and Division then the following pages:

5.5 The fifth section in chapter five

And

5.10 The tenth section in chapter five

Would appear in the Pages area as:


Figure 90.11 — Pages listed in the wrong order

I.e. the 5.10 Section appears before the 5.5 Section. GitHub puts them in the wrong order.

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.

⬆️ Top

90.5.3 Listing pages in the order you want

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 90.12 — Pages listed in the right order

The key is to always use leading zeros. This arrangement always works.

To summarise, the rules for this naming convention are:

Pages that start with a new Chapter should be named:

Cc Chapter title text.md

Pages that start with a new Section should be named:

Cc.Ss Section title text.md

And pages that start with a new Division should be named:

Cc.Ss.Dd Division title text.md

The rules are thus:

Cc, Ss and Dd must always be two numerical digits, leading spaces must be used where necessary
Ss and Dd must be preceded by a full stop character ., i.e. .Ss and ```.Dd``
The title text must be separated from the last numerical digit with a space character
The title text (the .md filename) must be correctly capitalised (this is how GitHub will generate the title).

⬆️ Top

90.6. Sidebars and footers

The sidebar and footer are optional components of the GitHub Wiki and are configurable by the user.

In Figure 90.9, the sidebar (point 4) is located in the top-right area below the GitHub generated Contents/pages section. The footer is at the bottom of the page (point 5).

By default there will be no sidebar or footer.

⬆️ Top

90.6.1 What are sidebars and footers?

In the simplest terms, a sidebar is a common area to top-right of all Wiki document pages. When you create a sidebar (see below), that sidebar will appear on every page in the Wiki.

Similarly, a footer is a common area that will, once created, appear at the bottom of 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 copyright or 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 90.9 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 template contains a full description of how to have different sidebars and footers for each Wiki page, it is explained fully in section xxx.

First of all let’s examine what GitHub intended with a sidebar and a footer:

⬆️ Top

90.6.2 Create a sidebar or footer in GitHub

If no sidebar or footer exists, GitHub will prompt for them to be made on the Home page:


Figure 90.13 — Creating a sidebar or footer

Clicking either option will open the correct editor and allow entries to be made.

Sidebars and footers that already exist can be edited from the home page by clicking the pencil symbols at the top right of each area (highlighted below for the sidebar):


Figure 90.14 — 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 xxx explains how to create individual sidebar and footer areas for each page.

⬆️ Top

90.6.3 Create a sidebar or footer locally

Sidebars and footers can also be created in a local copy of the Wiki and then pushed to GitHub, I use VS Code as my local text editor (hence the images below).

The sidebar and footer are stored in the files _Sidebar.md and _Footer.md in the root directory of the local repository. This can be seen below, the _Sidebar.md file is shown: