03 A Wiki folder structure

3A Wiki folder structure

It is perfectly possible to impose a folder structure on a GitHub Wiki, but it is not possible to do so from 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 (pages) area and allow them to be accessed without referring to the folder structure (see section 9.8). 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 ${\large \color{#446FBD}\text{/}\color{#c00000}\text{wiki}}$ directory).

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

⬆️ Top

3.1The default arrangement

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

${\large \color{#7030A0}\text{https:/}\text{/github.com}\color{#446FBD}\text{/}\color{#ED7D31}\text{[UserName]}\color{#446FBD}\text{/}\color{#00B050}\text{[RepositoryName]}\color{#446FBD}\text{/}\color{#c00000}\text{wiki}}$

In the case of this Wiki being discussed here, it is in:

${\large \color{#7030A0}\text{https:/}\text{/github.com}\color{#446FBD}\text{/}\color{#ED7D31}\text{practicalseries}\color{#446FBD}\text{/}\color{#00B050}\text{GitHub-Wiki-Design-and-Implementation}\color{#446FBD}\text{/}\color{#c00000}\text{wiki}}$

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

^{Figure 3.1 — The Wiki Home page}

In actuality, the link should be:

${\large \color{#7030A0}\text{https:/}\text{/github.com}\color{#446FBD}\text{/}\color{#ED7D31}\text{practicalseries}\color{#446FBD}\text{/}\color{#00B050}\text{GitHub-Wiki-Design-and-Implementation}\color{#446FBD}\text{/}\color{#c00000}\text{wiki}\color{#446FBD}\text{/}\color{#FF0000}\text{home}}$

Tip

The reason it is not necessary to use the home addition is that the GitHub Wiki server knows 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:

${\large \color{#7030A0}\text{https:/}\text{/github.com}\color{#446FBD}\text{/}\color{#ED7D31}\text{practicalseries}\color{#446FBD}\text{/}\color{#00B050}\text{GitHub-Wiki-Design-and-Implementation}\color{#446FBD}\text{/}\color{#c00000}\text{wiki}\color{#446FBD}\text{/}\color{#FF0000}\text{11-images}}$

The above will link to the ${\large \color{#446FBD}\text{Images}}$ page of this Wiki (note, if any spaces are in the name they must be replaced with a dash).

In all cases, it is not necessary to specify the .md extension, GitHub will figure this out .

In fact, if the .md extension is added, GitHub will not find the file (I think it adds .md to the filename and is now trying to find a file that ends .md.md and it can’t).

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 3.2 — The default GitHub folder arrangement for a Wiki}

⬆️ Top

3.2Create a sidebar or footer locally

This is a slight aside from the folder structure, but is necessary to explain how the folder structure impacts the sidebar and footer (in particular how it impacts individual sidebars and footers for different Wiki pages).

If there were no sidebar or footer created using GitHub, the _sidebar.md and _footer.md files will not be present in the root folder.

It is possible to create sidebars and footers in a local copy of the Wiki and then push them to GitHub. All that is required is that either or both the _sidebar.md and _footer.md files are created locally in the root directory (where the Home.md file is), the files must have some content.

A typical example of the _Sidebar.md file for this Wiki is shown below (in VS Code):

^{Figure 3.3 — Editing a sidebar in VS Code}

The above code renders like this (the bit you can see in the listing above is the navigation bar at the top of the image below):

^{Figure 3.4 — Rendered version of the sidebar}

Creating or changing these files within VS Code and pushing the changes to GitHub will change the common sidebar and footer used by all pages.

A full discussion of sidebars and footers and their contents is given in section 16.6 and section 16.7 (these relate to how they are constructed for the PracticalSeries Wiki pages).

⬆️ Top

3.3Page naming and Wiki limits

Before starting the folder structure, it is worth examining the page naming conventions used in the PracticalSeries Wikis. These to some extent determine the folder names that will be used in the Wiki folder structure.

It is also worth knowing the limits that GitHub imposes on Wikis and the files that can be included.

3.3.1Supported file types

Wiki content pages are generally Markdown files (.md), virtually all Wiki pages are Markdown files, but other filetypes are supported and show up in the GitHub generated contents area. The following file types are supported for page content:

Page Content Language	File extension
Markdown (default format for a Wiki)	`.md`
AsciiDoc	`.asciidoc`
Creole	`.creole`
MediaWiki	`.mediaWiki`
Org-mode	`.org`
Pod	`.pod`
RDoc	`.rdoc`
ReStructuredText	`.rest`
Textile	`.textile`
^{Table 3.1 — Wiki page content file types}

Important

Plain text .txt files and rich text files .rtf are not supported as page content platforms and will not appear in the contents area.

GitHub supports these common image files:

Image file	File extension
AV1 (Alliance for Open Media Video)	`.avif`
BMP (Bitmap)	`.bmp`
JPEG (Joint Photographic Experts Group)	`.jpg` or `.jpeg`
PNG (portable network graphic)	`.png`
GIF (graphic interchange format)	`.gif`
PSD (Photoshop document file)	`.psd`
SVG (scalable vector graphic)	`.svg`
WEBP (web picture format)	`.webp`
^{Table 3.2 — Wiki page renderable image formats}

GitHub supports these common video files:

Video file	File extension
MP4 (Moving Picture Experts Group 4)	`.mp4`
MOV (QuickTime movie format)	`.mov`
WEBM (web movie format)	`.webm`
^{Table 3.3 — Wiki page recognised video formats}

Important

Video files themselves cannot be played within a Wiki page, however, the formats are recognised as video files and file size limits are adjusted accordingly (see Section 3.3.4).

⬆️ Top

3.3.2Page names and numbering

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, point ① below:

^{Figure 3.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), point ②.

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

The second point is more problematic and was touched upon in Section 1.5.2.

The order of the pages in the Pages area is listed in alphanumeric order (based on the ASCII table https://www.ascii-code.com/ to those of a certain age, or nowadays the Unicode table https://www.unicode.org/charts/charindex.html ^💠1).

This means that if pages were numbered directly with chapter, section and division then the following pages:

${\large \color{#1F883D}\text{5.5\ The\ fifth\ section\ in\ chapter\ five}}$

And

${\large \color{#1F883D}\text{5.10\ The\ tenth\ section\ in\ chapter\ five}}$

Would appear in the Pages area as:

^{Figure 3.6 — Pages listed in the wrong order}

I.e. the ${\large \color{#1F883D}\text{5.10\ Section}}$ appears before the ${\large \color{#1F883D}\text{5.10\ 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 numbers must always be two digits and leading zeros must be used where necessary. This can be seen in the following example:

^{Figure 3.6 — Pages listed in the right order}

All pages within the PracticalSeries Wikis are given chapter, section and division numbers (with the exception of the Home page and some other special pages).

While it is necessary for the filenames to start with the chapter, section and division numbers (with leading zeros), any manually configured contents list (that links to these files) can show the abbreviated number (without leading zeros). The following diagram shows the numbering structure for the first two chapters of the this Wiki:

^{Figure 3.8 — Contents list for a Wiki}

The numbering is always in the format:

${\large \color{#1F883D}\text{Chapter.Section.Division}}$

Thus, ${\large \color{#1F883D}\text{1.5.2\ Contents\ area}}$ is division 2, of section 5 in chapter 1.

The corresponding page filename would be

${\large \color{#1F883D}\text{01.05.02\ Contents\ area.md}}$

The rules for these naming conventions are given in the following section:

⬆️ Top

3.3.3Rules for page numbering

The chapter, section and division numbering of pages within the PracticalSeries Wikis is important, it affects how the folders for each page are numbered in the Wiki folder structure. The following are the rules for page numbering:

	^{List 3.1 — Rules for page numbering}
❶ Always use a numbering structure:
	Chapter number only for small Wikis `Cc` Chapter and section `Cc.Ss` or Chapter Section and division `Cc.Ss.Dd`
❷ Pages that start at a chapter should be named:
	`Cc Chapter title text.md`
❸ Pages that start at a section should be named:
	`Cc.Ss Section title text.md`
❹ 4 Pages that start at a division should be named:
	`Cc.Ss.Dd Division title text.md`
❺ `Cc`, `Ss` and `Dd` must always be two numerical digits ❻ Leading zeros must be used where necessary ❼ `Ss` and `Dd` must always preceded by a full stop character (`.`) ❽ 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

Important

This structure only caters for chapter, section and division numbers in the range 0-99. This should be more than adequate for most document.

⬆️ Top

3.3.4Limits for Wiki pages

There are some absolute limits for the size of Wiki pages, generally, these are quite liberal and are unlikely to cause problems. These limits are:

^{List 3.2 — Wiki page file size limits}
❶ A Wiki can have a maximum of 5000 files within it (of any type) ❷ A Wiki page can have a maximum of 484,044 characters ❸ The maximum size for a Wiki page (`.md` file) is 0.5 MB ❹ The maximum size for images and videos is 10 MB ❺ The maximum size for any other file is 25 MB (pdfs, docs &c.) ❻ Files over 100 MB cannot be uploaded

The largest files within the Wiki associated with this document are some of the character tables in the Appendices (the largest is Appendix B.2 and the .md file is 501 kB, just less than the 512 kB or 0.5 MB limit). These all work, but occasionally, GitHub generates an error saying the page takes too long to render (reloading the page usually works).

The above limits do not generally cause any problems with Wiki pages (you are unlikely to hit any of them). With the PracticalSeries Wiki pages, other restrictions are imposed to manage page lengths and the splitting of text in to individual Wiki pages.

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.

All PracticalSeries Wikis use the chapter, section, division numbering Cc.Ss.Dd, In practice, the vast majority of PracticalSeries Wiki pages start at the chapter level (each page “mostly” starts at a new chapter). For very long chapters, the pages break at the section level. There are no breaks at the division level.

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

^{List 3.3 — Guidelines for Wiki pages}
❶ Limit the number of lines on a page to a maximum of 500 ❷ Limit the number of words on a page to a maximum of 4000 ❸ A new Chapter must always start on a its own Wiki page ❹ If splitting a chapter do so at a new section ❺ Avoid starting new pages at the division level ❻ A new page can start with a new division, but only when absolutely necessary ❼ Never start a new Wiki page with an inline (unnumbered) heading ❽ Never start a new Wiki page in the middle of body text

⬆️ Top

3.4A Practical Wiki folder structure

The default GitHub arrangement may be enough for small Wikis, but it is not sufficient for more complex Wikis like the PracticalSeries (PS) Wikis. These contain quite comprehensive sets of documentation and need a little more sophistication than is provided for with the basic GitHub structure. To do this, each Wiki page is stored in its own subfolder.

The mechanism described here is the one used throughout the PracticalSeries Wiki pages. It can be applied or adapted to any other GitHub Wiki

These are the principal reasons for using a folder structure within a Wiki:

^{List 3.4 — Reasons for using a folder structure}
❶ It allows each page to have its own, individual sidebar and footer ❷ It allows the pages to be better organised ❸ Each page subfolder has its own folders for images and data

In the case of this Wiki GitHub Wiki — Design and Implementation, only the Home page, a common logo image and the home page sidebar and footer is in the root directory of the Wiki repository:

All the other pages are in their own subfolder.

This page, for example, has the filename 03 A folder structure for a Wiki.md and is in the folder 03-0000.

It can be seen here in VS Code:

^{Figure 3.9 — A Wiki page subdirectory}

⬆️ Top

3.4.1Subfolder 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.:

${\large \color{#446FBD}\text{Cc-0000}}$

Thus, if a Wiki page starts at chapter 3, it will be in subfolder:

${\large \color{#446FBD}\text{03-0000}}$

If a page were to start at chapter 4, section 2 it would be in subfolder:

${\large \color{#446FBD}\text{04-0200}}$

If a page were to start at a Division, say chapter 11, section 12, division 15; it would be stored in subfolder:

${\large \color{#446FBD}\text{11-1215}}$

Tip

Starting pages at a division is not recommended and is generally avoided on the PracticalSeries Wiki pages — it’s there if you need it, but try not to do it.

The folder structure also accommodates Appendices. Appendices are numbered with a letter (A-Z) in place of a chapter number, the sections and divisions within an appendix are numbed in exactly the same was as normal chapters.

The folder name for Appendix B, would be:

${\large \color{#446FBD}\text{B-0000}}$

There is no need to put a leading zero before the appendix letter (these will automatically fall into the correct alphabetical order). This arrangement accommodates up to 26 appendices (A to Z), if more than this are required, it is better to us a numerical structure for appendices.

The folder structure for this Wiki looks like this (at the time of writing):

^{Figure 3.10 — A typical example of the Wiki folder structure}

Files for each Wiki page are stored in the specific folders. This can be seen in the following image (page files are shown in orange, the individual subfolders in white and the root folder is highlighted in blue. The individual sidebar files are in purple and the individual footer files in dark blue):

^{Figure 3.11 — This Wiki folder structure}

⬆️ Top

3.4.2Storing 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 3.12 — Storing images and data}

Figures are stored in a subfolder called:

${\large \color{#446FBD}\text{02-images}}$

And any data files are stored in

${\large \color{#446FBD}\text{04-data}}$

It can be seen in Figure 3.12 that there are three .png images stored for the page:

${\large \color{#446FBD}\text{01\ Introducing\ the\ GitHub\ Wiki.md}}$

The ${\large \color{#446FBD}\text{04-data}}$ folder is to store any other type of file that may be linked to a particular page (a pdf file in this case).

Footnotes:

Note

^💠1 If there is a worse website than the Unicode website I’d like to see it. It has a Circa 1989 feel, it’s impenetrable and virtually useless. If Tim Berners-Lee had seen it, he would have given up on the World Wide Web there and then.↩