In this Wiki, I’ve tried to explain (in some detail) how GitHub Wikis work and how Markdown and HTML can be used and abused to format the pages into something like and acceptable document format.

This section goes one step further. In this section I go through all the conventions I use to create the PracticalSeries Wiki pages. Obviously, the content is determined by whatever the Wiki pages are documenting, but the format and appearance is consistent across all the PracticalSeries Wiki page.

All of the conventions used within the PracticalSeries Wiki pages are given as examples in on the template page of the Wiki, here: Appendix E Template

⬆️ Top

All PracticalSeries Wiki pages have a standard arrangement, the following shows the typical arrangement (it’s a slightly abridged page to get everything in):

Figure 16.1 — A typical PracticalSeries page

All PracticalSeries Wiki pages have these areas:

The following sections discuss each of these areas in turn and list the various objects and elements contained within each area of the page.

⬆️ Top

Section 3 gave details of how to structure a Wiki folder arrangement and the naming conventions used to name files within the structure.

This section shows a practical implementation of that folder structure in relation to this Wiki.

The folder structure is shown below (split into two columns):

Figure 16.2 — The folder structure for this Wiki

⬆️ Top

Examining the contents of the root folder (on the GitHub website, the link to the root folder is: https://github.com/practicalseries/GitHub-Wiki-Design-and-Implementation/wiki/).

The unexpanded contents of the root folder are:

Figure 16.3 — The root folder

Here we can see multiple folders organised int chapter, section and division numbers in the format:

     ${\large \color{#446FBD}\text{cc-ssdd}}$

Where ${\large \color{#446FBD}\text{cc}}$ is the chapter number, ${\large \color{#446FBD}\text{ss}}$ the section and ${\large \color{#446FBD}\text{dd}}$ the division.

There are also four files:

The GitHub logo file is the logo at the top of each page:

Figure 16.4 — The logo image

If the Home page needs to display any images (other than the logo), then these are contained in the folder:

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

The folder ${\large \color{#446FBD}\text{00-0000}}$ being chapter zero, section zero is reserved for the Home page and any leading pages (such as the licence page).

Similarly, if the Home page has any data files (it does, the pdf version of this document), then these files are contained in the folder:

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

⬆️ Top

The PracticalSeries Wikis usually have one or more leading pages, they pretty much all have a licence page and during the development stages of the Wiki I include a “CaseNotes” page that contains a brief list of observations and points for current and upcoming items within the Wiki (a sort of aide-memoire of things I need to do).

All these leading pages live in the ${\large \color{#446FBD}\text{00-0000}}$ folder, they can be seen here:

Figure 16.5 — The 00-0000 folder

The ${\large \color{#446FBD}\text{00-0000/02-images}}$ folder contains the common images files used throughout the Wiki (for navigation bars, see section 15.1 and for image spacing, see section 11.4), these all start wi- (indicating Wiki image). Any images required by the Home page or any of the leading pages would also be stored in this folder (these would begin figm-).

⬆️ Top

Most folders in the structure have a .gitkeep file, this is a text file with the following contents:

# /* PRACTICALSERIES (c) 2021
# 
# *******************************************************************************
# Title :          FOLDER PLACEHOLDER                                    .GITKEEP
# *******************************************************************************
# 
# PRACTICALSERIES: Practical Series of Publications by Michael Gledhill
#                  Published in the United Kingdom
# 
#                  Email: [email protected]
#                  Web:   www.practicalseries.com
# 
# -------------------------------------------------------------------------------
# DETAILS
# 
# This is an empty placeholder file.
# 
# The Git and GitHub version control system will always ignore empty folders and
# will exclude them from the version control repository.
# 
# With website development it is important to maintain the correct folder 
# structure and the inclusion of empty folders within that structure is
# necessary.
# 
# The purpose of this file is to force Git and GitHub to include folders that 
# would otherwise be empty and thus not included in the repository.
# 
# There is a somewhat unofficial convention within the Git community that 
# such files are called .gitkeep.
# 
# -------------------------------------------------------------------------------
# 
# 
# MODIFICATION HISTORY:
# 
# This is a complete summary of all software modifications. 
# 
# Date          Issue    Author         Reason for Modification
# -------------------------------------------------------------------------------
# 07 Feb 2020   001.000  M. Gledhill    First release (all files updated)
# -------------------------------------------------------------------------------

By default Git (and by extension, GitHub) ignores any empty folder in a folder structure. An empty folder cannot be added to a repository (and since Wikis are also repositories, the too cannot have empty folders).

The .gitkeep file is a small text file that can be copied into an empty folder, forcing that folder to be added to the repository (or Wiki).

The name .gitkeep is a longstanding tradition amongst Git users for such a place holder file.

⬆️ Top

Every chapter has its own folder, these are always numbered:

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

Where ${\large \color{#446FBD}\text{cc}}$ is the two-digit chapter number (leading zeros must be used)

For example the chapter ${\large \color{#446FBD}\text{11\ Images}}$, and its associated images and data files are stored in folder:

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

These can be seen below:

Figure 16.6 — The 11-0000 folder

Expanding the folder shows all the images (5 of them, I’ve abbreviated the list for conciseness) stored in the 11-0000/02-image folder. The 11-0000/04-data folder is empty (apart from the.gitkeep file).

There is the 11 Images.md file and the _sidebar and _footer files for the page.

For the main chapter page (in the form cc-0000, i.e. no section number), the .md file name always has the form:

     ${\large \color{#446FBD}\text{cc\ Chapter\ Heading\ Text}}$

Where ${\large \color{#446FBD}\text{Chapter\ Heading\ Text}}$ is the plain English chapter title (in sentence case), in this case it is Images — the full filename being 11 Images.md.

The chapter filename should always start with a two-digit number followed by a space character. The ${\large \color{#446FBD}\text{Chapter\ Heading\ Text}}$ must be in sentence case and have proper spaces and punctuation between the words, the following are all correct examples:

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

     ${\large \color{#446FBD}\text{11\ Images.md}}$

     ${\large \color{#446FBD}\text{12\ Contents,\ collapsible\ content\ and\ footnotes.md}}$

⬆️ Top

The above all deal with pages that start at a new chapter. It is possible (for long chapters) that the chapter is broken into more than one page. In the PracticalSeries Wikis, such breaks always occur at a new section (never at a new division).

Where new pages start at a section, that section has its own folder, these are always numbered:

     ${\large \color{#446FBD}\text{cc-ss00}}$

Where ${\large \color{#446FBD}\text{cc}}$ is the two-digit chapter number and ${\large \color{#446FBD}\text{cc}}$ the two-digit section number (leading zeros must be usedin both cases).

For example the chapter 11 Images is split into two sections with the split occurring at section 11.5 (the first part is covered in the previous section, it is stored in folder 11-0000). The second part (and its images and data) is stored in folder:

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

Figure 16.7 — The section folder

Expanding the folder shows all the images (4 of them, I’ve abbreviated the list for conciseness) stored in the 11-0500/02-image folder. The 11-0500/04-data folder is empty (apart from the.gitkeep file).

The file name starts with the chapter and section number of the starting section (11.05 in this case), but the text remains that of the main chapter (Images in this case), the whole thing being 11.05 Images.md.

⬆️ Top

The page title area is entirely generated by GitHub, it looks like this:

Figure 16.8 — The title area of a page

The main thing about the title page is the title itself, point 1; This is in a 32 pt Segoe UI font (with a reduced weight, 400 not the usual 600).

The title displayed here is the name of the .md file for the page without the extension. In this case, the page file is 02 Cloning a Wiki.md and the page title is thus ${\large \color{#446FBD}\text{02\ Cloning\ a\ Wiki}}$.

The filename is the only thing we have control over in the title area.

The point in the above diagram are as follows:

⬆️ Top

The page heading area has the same format for every page in the PracticalSeries Wikis, there are both visible and unseen elements to the heading area:

Figure 16.9 — The heading area of a page

Point 1 is the logo for the Wiki (this is the same image on every page). This is the file:

     ps-github-wiki_log.svg

Stored in the root folder of the Wiki.

Point 2 is a Web ID badge that shows the chapter and section number of the page and an encoded date that shows when the page was posted to GitHub.

The Markdown behind the heading area is:

Markdown and GitHub output
${\large \color{#0050C0}\text{M\ A\ R\ K\ D\ O\ W\ N}}$ 🔽
<a name="idtop"></a> <img width="896px" src="./ps-github-wiki-logo.svg" alt="PAL Logo"> <p align="right"><img height="18" src="https://img.shields.io/badge/Web_ID-0200--djy-blue"></p>
${\large \color{#B00000}\text{G\ I\ T\ H\ U\ B}\space\ \space\text{O\ U\ T\ P\ U\ T}}$ 🔽
Table 16.2 — Standard_Markdown_HTML_Output_table

The first line <a name="idtop"></a> is the top of page marker

This is followed by the Logo image <img width="896px" src="./ps-github-wiki-logo.svg" alt="PAL Logo">

and finally, the Web ID badge <p align="right"><img height="18" src="https://img.shields.io/badge/Web_ID-0200--djy-blue"></p>

Examining each in turn:

⬆️ Top

The top of page marker is named anchor element that is used to identify the top of the page and allow navigation back to it (navigation to named elements was covered in section 9.5)

This top of page marker is completely invisible and does not render on the page (it is essentially a named anchor point, but the anchor point itself is empty, there is no text or href attribute). The Markdown for this is:

<a name="idtop"></a>

Every page in the PracticalSeries Wikis uses idtop as the name of the element at the top of the page.

This is the point navigated to by the links at the end of each section:

⬆️ Top

The Markdown behind the link is as follows:

**[:arrow_up: Top](#idtop)**
<HR>
<br>

The :arrow_up: is the emoji ⬆. The link is #idtop, this is the same name used in the top of page anchor name attribute preceded with a hash #. The link should be preceded with a blank line, the <hr> provides the horizontal line separating the sections and the <br> at the end give the correct spacing to the following text, there should be a further blank line between the last <br> and the next heading.

⬆️ Top

The logo image is the first visible element on each Wiki page. It is just a straight forward image (see section 11.2.1):

Markdown and GitHub output
${\large \color{#0050C0}\text{M\ A\ R\ K\ D\ O\ W\ N}}$ 🔽
<img width="896px" src="./ps-github-wiki-logo.svg" alt="PAL Logo">
${\large \color{#B00000}\text{G\ I\ T\ H\ U\ B}\space\ \space\text{O\ U\ T\ P\ U\ T}}$ 🔽
Table 16.5 — Logo image Markdown

It is an HTML image link <img> tag that displays the image ps-github-wiki-logo.svg that is stored in the Wiki root folder (hence the ./, current directory, that precedes the filename in the link, see section 9.8).

The first part width="896" sets the image to be the full width of the page.

The alt text is simply a textual description of what the image shows.

⬆️ Top

The Web ID is a right aligned Shields.IO badge (see section 15.2):

The Markdown is:

<p align="right"><img height="18" src="https://img.shields.io/badge/Web_ID-0200--djy-blue"></p>

The Web ID badge is a Shields.IO static badge, the badge image is contained in a <p align="right"> tag, this forces the badge to appear on the right-hand edge of the page.

The badge itself is within an <img> tag that sets the image height to 18 px (slightly smaller than the 20 px default). The badge label is Web_ID (the underscore appears as a space, see section 15.2), the badge text is 0200--djy (the double dash is the escape code for a dash, section 15.2). Finally, the badge text background is set to the default blue colour.

The Web ID badge text 0200--djy is in two parts: first a four-digit number, this contains the chapter and section number in the form ccss (section number is 00 for the start of a chapter).

The second part is three alphabetical characters djy in this case. This is an encoded version of the date the page was posted to GitHub.

The characters are in the form XYZ and are alphabetical (Roman) characters with the following meanings:

Thus djy is the date 25th October 2024.