91 Imposing a folder structure on a Wiki

91.     Imposing a folder structure on a Wiki

It is perfectly possible to impose a folder structure on a GitHub Wiki, but it is not possible to do so within GitHub itself. It must be done in a local repository (I use VS Code as my editor) and the folders then pushed back to GitHub.

It should be noted that GitHub largely ignores any applied folder structure, it will list any markdown files (files ending .md) in its contents area and allow them to be accessed without referring to the folder structure (see section xxx). Other files need to be referred to (as a minimum) with the full path from the root directory of the Wiki (I.e. all folders and subfolders that follow the /wiki/ directory).

The big advantage to using a folder structure is that it allows different sidebars and footers for the pages in each subfolder.

⬆️ Top

91.1.     The default arrangement

By default, any page created by GitHub in a Wiki will be in the repository folder:

   https://github.com/[user]/[repositoryName]/wiki

In the case of the PAL Software Wiki, it is in:

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

Entering the above link in a web browser will take you to the Home page of the PAL Software Wiki:

Figure 91.1 — The PAL Software Wiki home page

In actuality, the link should be:

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

Or more properly still:

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

Note

All of these work (the reason it is not necessary to use the home addition or the file extension is that the GitHub Wiki server know that if no page is specified, it will default to the home page. This is similar to a website not having to specify index.html in their base URL).

To link to another page, the name of the page must be included:

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

The above will link to the template page (note, if any spaces are in the name they must be replaced with a dash)

If all the Wiki pages were built using GitHub and if that Wiki repository were copied to a local machine, everything would be in one directory, like this:

Figure 91.2 — The default GitHub arrangement for a Wiki

Managing the repository locally gives much more flexibility to the structure of the repository.

⬆️ Top

91.2.     A practical Wiki folder structure

The default arrangement may be enough for small Wikis, but it is not sufficient for more complex Wikis like the PracticalSeries (PS) Wiki repositories, these contain quite comprehensive sets of documentation and need a little more sophistication. This sophistication is achieved by storing each Wiki page in its own subfolder.

The mechanism described here is the one used throughout the PracticalSeries Wiki pages (the ones you are looking at now).

There are two principal reasons for using a folder structure within a Wiki:

1. It allows each page to have its own, individual sidebar and footer

2. It allows the pages to be better organised, each page subfolder has its own folders for images and data

The PAL Software Wiki only has the Home page, a common logo image and the home page sidebar and footer in the root directory of the Wiki repository:

• Home.md

• pal-logo-github-wiki.svg

• _Sidebar.md

• _Footer.md

All the other pages (including this one) are in their own subfolder. This page (91 Imposing a folder structure on a Wiki.md), for example, is in the folder 91-0000 , it can be seen here in VS Code:

Figure 91.3 — Wiki page subdirectory

⬆️ Top

91.2.1       Page Numbering in the Wiki structure

All pages within the PAL Software Wiki are given chapter, section and division numbers (with the exception of the Home page, the CaseNotes page and the Licence page — all of which are covered in section xxx), the following diagram shows the folder and file structure for the first two chapters of the PAL Software Wiki:

Figure 91.4 — Chapter, section and division numbering

The numbering is always in the format:

Chapter.Section.Division

Thus, 2.1.3 Built-in system blocks is Division 3, of Section 1 in Chapter 2.

⬆️ Top

91.2.2       Rules for page numbering

The rules for how Chapters, Sections and Divisions are split into Wiki pages is fairly arbitrary and generally depends on the resultant length of the Wiki page.

To give some idea of the (very) rough rules of thumb employed on PS Wiki pages, the following conditions are applied:

1. Limit the number of lines on a page (ignoring images, tables and code fragments) to a maximum of 200

2. Limit the number of words on a (ignoring images, tables and code fragments) to a maximum of 2500

Most pages will be much shorter than this.

There are some other rules:

1. A new Chapter must always start on a its own Wiki page (it must not occur partway down a page)

2. If splitting a chapter do so at a new Section (rather than at a new Division) a new page can start with a new Division, but only when absolutely necessary

3. Never start a new Wiki page with an inline heading (see section xxx)

4. Never start a new Wiki page in the middle of body text (it must always be at a Chapter, Section or Division break)

To give some indication, the PAL Software Wiki page (https://github.com/practicalseries/PS2001-pal-software/wiki) has the whole of Chapter 1 (Introducing the PAL) on a single Wiki page (the Home page).

The second PAL Software Wiki page has the start of Chapter 2 (The Controller software and structure) all the way down to Division 2.1.4 (Block numbering and quantities).

The third page starts at Section 2.2 (Execution of Controller software) and contains the remaining sections of Chapter 2.

⬆️ Top

91.2.3       Subfolder names for Wiki pages

Each PS Wiki page is stored in its own subfolder. The subfolder is simply a number in the format: Cc-SsDd

Where Cc is the Chapter number, Ss is the Section number and Dd is the Division number (all with leading zeros where required).

Thus, a Wiki page subfolder is made up of the Chapter, Section and Division number of the first heading on the page. If it is a new chapter, then Ss and Dd will be zero, i.e.:

   Cc-0000

This can be seen with the second page of PAL Software Wiki, it starts at Chapter 2, and is in subfolder:

   02-0000

The third page of the PAL Software Wiki starts at Chapter 2, Section 2 and is in subfolder:

   02-0200

If a page were to start at a Division, say Chapter 11, Section 12, Division 15; it would be stored in subfolder

   11-1215

⬆️ Top

91.2.4       Page names for Wiki pages

There are two things of importance when naming pages, the first is that GitHub always displays the page filename name at the top of the Wiki page:

Figure 91.5 — Page name displayed at top of a Wiki page

The second point is that the page filename is also listed in the GitHub generated Pages section (effectively a contents list).

The first point isn’t particularly serious, but the name should match the first heading on the page (in this case Execution of Controller software).

The second point is slightly more problematic, the order of the pages in the Pages area is determined by GitHub and it lists the pages in alphanumeric order (based on the ASCII table https://www.ascii-code.com/ order of characters). This was covered briefly in Section 91.2, but is explained more fully here:

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 91.3 — 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.

To get round this problem Chapter, Section and Division number must always be two digits and leading zeros must be used where necessary. This can be seen in the following example

Figure 91.4 — 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:

1. Cc, Ss and Dd must always be two numerical digits, leading spaces must be used where necessary

2. Ss and Dd must be preceded by a full stop character ., i.e. .Ss and ```.Dd``

3. The title text must be separated from the last numerical digit with a space character

4. The title text (the .md filename) must be correctly capitalised (this is how GitHub will generate the title).

For the example shown in Figure 91.7, the repository would have the following files:

Figure 91.8 — Page naming conventions in a folder structure

The page files are shown in orange, the individual subfolders in white and the root folder (on the local drive) is highlighted in blue.

The folder structures and files for the PAL Software Wiki are shown below (as of the time of writing):

Figure 91.9 — PAL Software Wiki folder structure

Again the page files are shown in orange, the individual subfolders in white and the root folder (on the local drive) is highlighted in blue. The individual sidebar files are in purple and the individual footer files in light blue.

⬆️ Top

91.2.5       Storing images and other data

Images and data for a particular page are stored in two separate folders within the subfolder for a particular page, this can be seen here:

Figure 91.10 — Storing images and data

Figures are stored in a subfolder called

   02-images

And any data files (there are none yet) are stored in

   04-data

It can be seen in Figure 90.22 that there are three .png images stored for the page:    02.02 Execution of Controller software.md

The 04-data folder is to store any other type of file that may be linked to a particular page (say a pdf file that is not stored anywhere else).

⬆️ Top

91.3.     Different sidebars and footers for Wiki pages

It was mentioned earlier (section 91.2) that the PS Wiki pages require the ability for each Wiki page to have its own sidebar and footer (rather than using the default sidebar and footer created using GitHub). It turns out that it is remarkably easy, the only problem being that it has to be done on a local machine and then pushed to GitHub. It can’t be done via the GitHub directly.

To make a sidebar and footer unique to a page, or to a group of pages, simply put the page in a subfolder and then create the files _Sidebar.md and _Footer.md within that same subfolder and the these will be used in place of the default sidebar and footer files in the root directory.

It can be seen here:

Figure 91.11 — Individual sidebars and footers for different pages

GitHub Wikis always use the _Sidebar.md and _Footer.md files in the current directory as the page being displayed in preference to those in the root folder.

In the image above, both the CaseNotes md and Licence.md pages have the same sidebar and footer, this is because they are both in the same subfolder 00-0000.

It really is that simple.

Note

If there is no _Sidebar.md or _Footer.md files in the current subdirectory, GitHub will use the default _Sidebar.md or _Footer.md file in the root directory (containing the Home.md file) instead.