16 PracticalSeries Wiki conventions

16PracticalSeries Wiki conventions

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

16.1The PracticalSeries Wiki page

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:

	^{List 16.1 — PracticalSeries Wiki page areas}
❶ Title area	This is generated by GitHub and cannot be reconfigured; the only configurable item is the page name
❷ Heading area	The heading area contains a logo picture and a WebID badge that shows the chapter and section number of the page (along with a revision code)
❸ Main body area	This is the main body text area, it contains headings, text, tables, images, links &c as required
❹ Footer	The footers all have an identical format: a navigation bar (different for each page), copyright information, common links to the top of page, email and the PracticalSeries website and a location badge showing the chapter and section number of the footer
❺ Sidebar	The sidebars all have an identical format: a title (Wiki contents) and a location badge showing the chapter and section number of the sidebar. Followed by a navigation bar (different for each page) and a table of contents. The last part of the sidebar is a link to the bottom of the page.

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

16.2The PracticalSeries folder structure

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

16.2.1The root folder and home page

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:

File	Function
`_footer.md`	The footer Markdown file for the Home page
`_sidebar.md`	The sidebar Markdown file for the Home page
`Home.md`	The Home page Markdown file
`ps-github-wiki_log.svg`	The logo image (shown in the heading area of each page)

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

16.2.2Leading pages

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}

Note

All the leading pages (in this case CaseNotes.md and Licence.md) share the same sidebar and footer, this is possible because these leading pages are usually outside the normal next chapter/previous chapter navigation hierarchy.

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

16.2.3.gitkeep files

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

^Text

${\large \color{#ED7D31}\text{T\ E\ X\ T}}$ 🔽

# /* 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)
# -------------------------------------------------------------------------------

^{Table 16.1 — .gitkeep file contents}

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

16.2.4Folder and Markdown file names

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

Wiki pages that start at a section

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

16.3The page title area

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:

	^{List 16.2 — Title area components}
❶ Title	TThe page `.md` filename without the extension
❷ User	Username of the last person to modify the page
❸ Modification date	The date of the last modification
❹ Revisions	The number of revisions made to the page Clicking will navigate to the modification history
❺ Buttons	Edit and New page buttons (only visible if modification privileges have been granted)

⬆️ Top

16.4The page heading area

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 <img height="18" src="https://img.shields.io/badge/Web_ID-0200--djy-blue">

Examining each in turn:

⬆️ Top

16.4.1Top of page marker

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:

^Markdown
${\large \color{#0050C0}\text{M\ A\ R\ K\ D\ O\ W\ N}}$ 🔽
<a name="idtop"></a>
^{Table 16.3 — Top of page marker}

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:

^{Markdown and GitHub output}
${\large \color{#0050C0}\text{M\ A\ R\ K\ D\ O\ W\ N}}$ 🔽
[:arrow_up: Top](#idtop) <HR> <br>
${\large \color{#B00000}\text{G\ I\ T\ H\ U\ B}\space\ \space\text{O\ U\ T\ P\ U\ T}}$ 🔽
⬆️ Top
^{Table 16.4 — Top of page navigation link}

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   at the end give the correct spacing to the following text, there should be a further blank line between the last   and the next heading.

⬆️ Top

16.4.2Logo image

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

16.4.3Web ID badge

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

The Markdown is:

^{Markdown and GitHub output}
${\large \color{#0050C0}\text{M\ A\ R\ K\ D\ O\ W\ N}}$ 🔽
<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.6 — Web ID badge}

The Web ID badge is a Shields.IO static badge, the badge image is contained in a  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.

Note

This encoded date is just for me, it would be perfectly possible to just use the modification date in the title area, but I wanted something that I had direct control over — it allows me to break the rules when I want to.

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