16 PracticalSeries 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:
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:
| ❶ 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. |
| List 16.1 — PracticalSeries Wiki page 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.
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 |
|---|
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:
Where
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:
The folder
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:
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
|
| 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 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-).
Most folders in the structure have a .gitkeep file, this is a text file with the following contents:
| Text |
|---|
|
|
# /* PRACTICALSERIES (c) 2021
#
# *******************************************************************************
# Title : FOLDER PLACEHOLDER .GITKEEP
# *******************************************************************************
#
# PRACTICALSERIES: Practical Series of Publications by Michael Gledhill
# Published in the United Kingdom
#
# Email: mg@practicalseries.com
# 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.
Every chapter has its own folder, these are always numbered:
Where
For example the chapter
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:
Where 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
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:
Where
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:
|
| 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.
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
The filename is the only thing we have control over in the title area.
The point in the above diagram are as follows:
| ❶ 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) |
| List 16.2 — Title area components |
|---|
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 |
|---|
|
|
<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>
|
|
|
|
|
| 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:
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 |
|---|
|
|
<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:
The Markdown behind the link is as follows:
| Markdown and GitHub output |
|---|
|
|
**[:arrow_up: Top](#idtop)**
<HR>
<br>
|
|
|
|
|
| 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 <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.
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 |
|---|
|
|
<img width="896px" src="./ps-github-wiki-logo.svg" alt="PAL Logo">
|
|
|
|
|
| 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.
The Web ID is a right aligned Shields.IO badge (see section 15.2):
The Markdown is:
| Markdown and GitHub output |
|---|
|
|
<p align="right"><img height="18" src="https://img.shields.io/badge/Web_ID-0200--djy-blue"></p>
|
|
|
|
|
| Table 16.6 — Web ID badge |
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.
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:
| Character | Meaning | Encoding |
|---|---|---|
X |
The year | a=2021, b=2022 … &c. |
Y |
The month | a=January, b=February … &c. |
Z |
The day | a=1, b=2, …, z=26, A=27, … E=31 |
Thus djy is the date 25th October 2024.
This is a big section; the body text can contain absolutely anything (it is whatever you want to write).
That said, there are a lot of common things that can appear in main body area and any page will almost certainly use a subset of them, this section contains examples of all the following:
|
❶ Common elements (things on every page) | |
|
|
|
❷ Heading ❸ Tables ❹ Images ❺ Lists ❻ Code fragments ❼ Formulae | |
| List 16.3 — Main area components | |
|---|---|
The PracticalSeries Wiki pages have certain common elements within the main body area of a page, the first is an end of page marker, the second is how sections and divisions are separated from each other. Taking these in turn:
The horizontal line (see section 6.3) indicating the end of the page is separated from the last text (the Lorem ipsum in the above image) by two lines, the <br><br>. The horizontal line is HTML version <hr>.
The end of page marker is analogous to the top of page marker (see section 16.4.1), it is a named anchor element that is used to identify the end of the page and allow navigation back to it (navigation to named elements was covered in section 9.5)
The end of page marker is completely invisible and does not render on the page (it is just a named anchor point, but the anchor point itself is empty, there is no text or href attribute). The Markdown for this is:
| Markdown |
|---|
|
|
<a name="idend"></a>
|
| Table 16.8 — End of page marker |
This is the last line of every Wiki page
Navigation links to the end of page marker are always in the sidebar, itlooks like this:
| Markdown and GitHub output | |
|---|---|
|
|
|
<table align="center"><tr>
<td><a href="#idend"><strong>⬇️ End of page</strong></a></td>
</tr></table>
| |
|
|
|
| |
| Table 16.9 — End of page navigation |
The :arrow_down: is the emoji ⬇. The link is #idend, this is the same name used in the end of page anchor name attribute preceded with a hash #. The link should be preceded with a blank line, the link is contained within a central table that places a box around the link.
Each section in a chapter has a common look and feel before the start of the next section (with the exception of the last section on a page, this is simply followed by the end of page marker discussed in the previous section)
Each section ends with a link to the top of the page and a horizontal bar separating the sections (highlighted below):
|
| Figure 16.10 — End of section |
|---|
The Markdown is:
| Markdown and GitHub output |
|---|
|
|
**[:arrow_up: Top](#idtop)**
<HR>
<br>
|
|
|
|
|
| Table 16.10 — End of section |
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.
Note
This was also discussed in section 16.4.1
Headings in the PracticalSeries Wikis are standardised:
| Level | Chapter, section, division | Examples |
|---|---|---|
| Level 1 | Chapter only | |
| Level 2 | Chapter and section | |
| Level 2 | Chapter, section and division | |
| Level 4 | Inline headings (not indented, indented and trailing line) |
|
| Table 16.11 — PracticalSeries headings | ||
The first three level headings (1 to 3) are numbered with chapters, chapters and sections and chapters, section and divisions respectively.
Examining these on a Wiki page, it looks like this:
|
| Figure 16.11 — Headings and different numbering arrangements |
|---|
In all cases, the heading numbers start on left edge of the main body area (left-edge of the page). The heading text is indented 120 pixels from the left edge (as shown).
The heading text, irrespective of heading level, all line up at the same indentation.
Level 4 headings are inline headings and do not have a section number. In this case, there are two versions, one indented (to the same level as numbered headings) and one without indentation. It’s personal preference which to use, I tend to go for the non-indented one.
There is a slight variation of the non-indented level 4 heading which has a trailing line at the end.
Where headings are numbered, leading zeros are not used (unlike with folder names and Web IDs), this is proper typographical practice for headings.
| Markdown |
|---|
|
|
# 1<!-- H1--><img width="105" height="1" src="00-0000/02-images/wi-spacer.png" alt="Indent">Heading level 1
# 20<!-- H1--><img width="083" height="1" src="00-0000/02-images/wi-spacer.png" alt="Indent">Heading level 1
## 1.1<!-- H2--><img width="094" height="1" src="00-0000/02-images/wi-spacer.png" alt="Indent">Heading level 2
## 2.20<!-- H2--><img width="073" height="1" src="00-0000/02-images/wi-spacer.png" alt="Indent">Heading level 2
## 12.5<!-- H2--><img width="077" height="1" src="00-0000/02-images/wi-spacer.png" alt="Indent">Heading level 2
## 13.21<!-- H2--><img width="067" height="1" src="00-0000/02-images/wi-spacer.png" alt="Indent">Heading level 2
### 1.1.1<!-- H3--><img width="085" height="1" src="00-0000/02-images/wi-spacer.png" alt="Indent">Heading level 3
### 2.1.10<!-- H3--><img width="071" height="1" src="00-0000/02-images/wi-spacer.png" alt="Indent">Heading level 3
### 3.11.4<!-- H3--><img width="071" height="1" src="00-0000/02-images/wi-spacer.png" alt="Indent">Heading level 3
### 12.1.2<!-- H3--><img width="071" height="1" src="00-0000/02-images/wi-spacer.png" alt="Indent">Heading level 3
### 12.13.5<!-- H3--><img width="060" height="1" src="00-0000/02-images/wi-spacer.png" alt="Indent">Heading level 3
### 14.18.21<!--H3--><img width="052" height="1" src="00-0000/02-images/wi-spacer.png" alt="Indent">Heading level 3
#### <!-- H4--><img width="120" height="1" src="00-0000/02-images/wi-spacer.png" alt="Indent">Heading level 4
#### <!-- H4-->Heading level 4
#### <!-- H4--><u>Heading_level_4<!-- Extended line -->     </u>
|
| Table 16.12 — Typical heading Markdown |
Heading levels 1 to 3 all have a very similar format, as follows (I’ve removed the comments to make it fit better on the page):
| Markdown |
|---|
|
|
## 1.1<img width="094" height="1" src="00-0000/02-images/wi-spacer.png" alt="Indent">Text
|
Headings are covered in section 6.10, but these headings are slightly different.
The heading starts with hashes, one hash # for level 1, two ## for level 2, three ### for level 3 and four #### for level 4.
The PracticalSeries Wikis only use four level headings.
The starting hashes are always followed by a space for clarity.
Note
The space is not actually required, the heading will render in exactly the same way if the space is not included (the space doesn’t add any space to the rendered output, GitHub ignores it). By convention, the space is always included, it makes the Markdown easier to read.
The space is followed by the number of the chapter (and section and division depending on the heading level).
Level 1 headings just have the chapter number, level 2 headings have the chapter number and section number separated by a full stop. Level 3 have chapter, section and division number with a full stop between chapter and section and another full stop between section and division.
In all cases, there is no full stop at the end of the number.
The number is followed by a comment field that identifies the heading level (e.g. <1-- H1 -->).
The next bit is an image that gives the spacing between the end of the number and the start of the heading text. This is an <img> tag, linking to the image wi-spacer.png (this image is available to down load here: wi-spacer.png and is discussed in section 11.4).
The image is a 1 pixel by 1 pixel transparent png image. Being transparent, the image is always invisible on a web page, but by setting its width (and keeping its height at 1 px), it can be used to create a space between the heading number and the heading text (again see section 11.4 for details).
The image tag is in the form:
Where
It can be seen that the width varies for each heading type and the number of digits in the heading number. The image itself is stored in the folder 00-0000/02-images. The image is given the alt text of Indent to clarify its meaning.
Finally comes the heading text. This should always be in sentence case (first letter capitalised along with proper nouns), it is not a title and should not use title case (all words capitalised except for articles, conjunctions and prepositions).
The template page of this Wiki contains a full set of headings, each with the appropriately sized image for the various combinations of one-digit and two-digit chapter, section and division numbering.:
Take a look at the following:
|
| Figure 16.12 — Heading number widths |
|---|
The code here is this:
| Markdown |
|---|
|
|
# 0<img width="100" height="1" src="00-0000/02-images/wi-spacer.png" alt="Indent">Heading
# 1<img width="100" height="1" src="00-0000/02-images/wi-spacer.png" alt="Indent">Heading
# 4<img width="100" height="1" src="00-0000/02-images/wi-spacer.png" alt="Indent">Heading
|
In each case, the spacing image is the same
The top heading (with the number 0) is correct, the heading text is 120 px from the left edge of the page.
The next two lines are wrong, the one starting with 1 is too far to the left and the one starting with a 4 is too far to the right.
These inaccuracies arise because the font use to display the numbers and text (Segoe UI) is a non-proportional font. This means the characters in the font are different widths, a “W” is wider than an “i” for example.
This is also true of numbers, with the Segoe UI font, the number 1 is the narrowest, followed by the number 7, numbers 0, 2, 3, 5, 6, 8, and 9 are all the same width and slightly wider than the 7. Number 4 is the widest.
The difference is amplified by repeating each character between blocks (10 repetitions of each number per line):
|
| Figure 16.13 — Relative withs of different number characters |
|---|
The dotted orange line coincides with the extent of the zero character.
This difference it character widths means that the image spacer in each heading has to be adjusted for the numbers in question whenever the number contains a 1, a 4 or a 7.
This becomes slightly more complicated when the heading incorporates section and division numbers, particularly where each number may be 1 or 2-digits.
Again, the template contains a full set of combinations.
Heading for appendices are also supported, these have the following appearances:
The difference here is that the chapter number is always a capital letter.
This leads to more combinations for the image spacer, particularly since most of the capital letter widths vary.
Again a full (probably) set of combinations is available on the template page:
You may be wondering how the inclusion of an <img> tag in a heading affects any links to that heading in a table of contents (TOC) or other link.
The answer is it doesn’t, when converting the heading to a TOC or link, the rules first discussed in section 9.3.1 and reproduces here still apply:
The
| ❶ |
There is only one hash `#` before the |
| ❷ | All text is converted to lowercase |
| ❸ | Spaces are converted to a single dash |
| ❹ | If multiple consecutive spaces are present, they are converted to a single dash |
| ❺ | Special space characters (see section 7.2) are ignored |
| ❻ | Any HTML tags are ignored (tags and attributes between `<>`) |
| ❼ | Any comments within the heading (text between ``) are ignored |
| ❽ | Numbers (0 to 9) are included |
| ❾ | All non-alphanumeric characters are ignored |
| List 16.4 — Rules for converting a heading |
|---|
So the heading:
| Markdown |
|---|
|
|
## 1.1<img width="094" height="1" src="00-0000/02-images/wi-spacer.png" alt="Indent">Heading name
|
Becomes the following link (in a TOC):
| Markdown |
|---|
|
|
[Heading name](#11heading-name)
|
The <img> tag is completely ignored as are any comments <!-- -->.
The PracticalSeries Wikis almost always use HTML tables, largely because the tables are usually centred on the page (not possible with Markdown tables) and each table has a caption at the bottom that spans the columns (again not possible with Markdown tables). This being an example:
| Markdown and GitHub output | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
|
|||||||||||||||
<table name="t-16-14" align="center"><!-- TABLE START (BLANK LINE ABOVE) -->
<!-- Header row --> <tr>
<th width="200" align="left">Character</th>
<th width="200" align="left">Name</th>
<th width="200" align="center">Escape symbol</th>
</tr>
<!-- Data row --> <tr>
<td align="left">\</td>
<td align="left">Backslash</td>
<td align="center">\\</td>
</tr>
<!-- Data row --> <tr>
<td align="left">`</td>
<td align="left">Backtick</td>
<td align="center">\`</td>
</tr>
<!-- Data row --> <tr>
<td align="left">*</td>
<td align="left">Asterisk</td>
<td align="center">\*</td>
</tr>
<!-- CAPTION --> <tr><th colspan="3" align="center"><sup>
<!-- CAPTION TEXT --> Table 16.14 — Markdown escape characters
</sup></th></tr>
</table>
<br clear="all"> <!-- TABLE END (BLANK LINE BELOW) -->
| |||||||||||||||
|
|
|||||||||||||||
| |||||||||||||||
| Table 16.14 — A simple table | |||||||||||||||
The table starts with the HTML <table> tag with various attributes:
| Markdown |
|---|
|
|
<table name="t-16-14" align="center">
|
All PracticalSeries tables have a name attribute, in the form: t-cc-nn, where cc is the chapter number containing the table and nn is the consecutive numbering of the tables within the chapter, in this case it is t-16-14 meaning it is the fourteenth table in chapter 16.
This name attribute allows navigation to the table from any point in the Wiki where it is referenced (see below for the navigation link details).
The align attribute determines where the table appears on the page, PracticalSeries Wiki tables are usually centred on the page so the alignment is set to center. Use left or right to align the table to either side of the page. Be aware of the word wrap problems that this can entail (see section 10.2.3)
The header row of the table is optional (it is not necessary to have a header row, unlike Markdown tables which have to have one). The header row looks like this:
| Markdown |
|---|
|
|
<!-- Header row --> <tr>
<th width="200" align="left">Character</th>
<th width="200" align="left">Name</th>
<th width="200" align="center">Escape symbol</th>
</tr>
|
This particular table is three columns wide, add or remove <th> lines as required to give more or fewer columns. Each cell within the row has its own horizontal alignment (align attribute), if vertical alignment is required (by default the cell will vertically align in the middle of the cell), use the valign attribute, see section 10.2.7 for details.
The header row is also used to specify the width of each column with the width attribute. In this case, each row is set to 200 px.
There now follows multiple sets of data rows:
| Markdown |
|---|
|
|
<!-- Data row --> <tr>
<td align="left">\</td>
<td align="left">Backslash</td>
<td align="center">\\</td>
</tr>
|
These are similar to the header rows; the alignment of each cell is specified and vertical alignment can also be added if required. Add as many data rows as are required.
The data rows are followed by a caption row (this is the bit at the bottom of the table that gives the table number):
| Markdown |
|---|
|
|
<!-- CAPTION --> <tr><th colspan="3" align="center"><sup>
<!-- CAPTION TEXT --> Table 16.14 — Markdown escape characters
</sup></th></tr>
|
There are a few things here.
Firstly, the caption cell is a heading cell <th> not <td>, this puts the caption in a bold font (saving the use of a <strong> tag).
The caption spans the full width of the table; in this case there are three columns, hence the colspan="3" attribute, if the table had two columns, this would become colspan="2" &c.
The caption is always centred across the width of the table, hence the align="center".
The caption text always has the form: Table x.y — Description.
Where x and y are the chapter number and sequential table number within the chapter (these are the same as the numbers given in the t-cc-nn name at the start of the table, but without leading zeros), in this case it is 16.14.
The — is an em dash (—) use to separate the table number from the description that follows "Markdown escape characters" in this case.
The table terminates with:
| Markdown |
|---|
|
|
</table>
<br clear="all"> <!-- TABLE END (BLANK LINE BELOW) -->
|
The <br clear="all"> is used to stop any text wrapping around the table (see section 10.2.3).
Each table should be preceded and followed by a blank line.
The naming of each table means that a link can be made to the table from any page within the Wiki (or even from an external website).
Using the previous table as an example, this had the name t-16-14. To link to this table from a point within the same Wiki page, the link would be:
| Markdown and GitHub output |
|---|
|
|
This is a link to <a href="#t-16-14">Table 16.14</a>.
|
|
|
|
This is a link to Table 16.14. |
| Table 16.15 — Link to a table |
If linking from a different page in the Wiki, the destination page must also be referenced, in this case it is on the this page, so the link becomes:
| Markdown |
|---|
|
|
This is a link to <a href="pagennn#t-16-14">Table 16.14</a>.
|
The destination page is added prior to the #.
Finally, to link to the table from an external website, the full URL for the Wiki page must be used, in this case it is:
| Markdown |
|---|
|
|
This is a link to <a href="https://github.com/practicalseries/GitHub-Wiki-Design-and-Implementation/
wiki/pagennn#t-04-06">Table 16.14</a>.
|
A full discussion of these types of links is given in section 9.5.
The PracticalSeries predominantly uses HTML tables, it does, however, use Markdown tables occasionally. These are usually in appendices, for example the emoji tables of appendix B are Markdown tables:
| Markdown and GitHub output | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
|
||||||||||||
#### Face Glasses
|Emoji<br>(No.)|Short Name (gitHub)<br>Short Name (Unicode CDLR)|Esc code (Dec)<br>Esc Code (Hex)|
|:---:|:---|:---|
|😎<br>74|GitHub: `:sunglasses:`<br>CLDR: `smiling face with sunglasses`|<sub>&#128526;</sub><br><sup>&#x1F60E;</sup>|
|🤓<br>75|GitHub: `:nerd_face:`<br>CLDR: `nerd face`|<sub>&#129299;</sub><br><sup>&#x1F913;</sup>|
|🧐<br>76|GitHub: `:monocle_face:`<br>CLDR: `face with monocle`|<sub>&#129488;</sub><br><sup>&#x1F9D0;</sup>|
| ||||||||||||
|
|
||||||||||||
Face Glasses
| ||||||||||||
| Table 16.16 — A Markdown table |
It is a straight forward Markdown table of the type discussed in section 10.1 (albeit with more <br> tags than is usual). These tables do not have captions or table numbers (name).
Such tables are used where required. If the data is in a spread sheet or something that can easily be converted to Markdown and doesn’t require the formatting that can only be achieved with HTML.
PracticalSeries images are always contained in a table (this time it’s my other dog, Matilda, a puppy, or possibly a space alien, at the time the picture was taken):
|
| Figure 16.14 — Matilda the saluki |
|---|
The code behind this is very similar to the table code:
| Markdown |
|---|
|
|
<table name="f-16-14" align="center"><!-- FIGURE START🔽🔽(BLANK LINE ABOVE) -->
<!-- Figure row --> <tr><td>
<!-- FIGURE --> <img width="600" src="./16-0000/02-images/figm-16-14.png" alt="Matilda the saluki">
</td></tr>
<!-- CAPTION --> <tr><th align="center"><sup>
<!-- CAPTION TEXT --> Figure 16.14 — Matilda the saluki
</sup></th></tr>
</table> <!-- FIGURE END 🔼🔼(BLANK LINE BELOW) -->
|
| Table 16.17 — A PracticalSeries figure |
The figure table starts with the HTML <table> tag with various attributes:
| Markdown and GitHub output |
|---|
|
|
<table name="t-16-17a" align="center">
|
All PracticalSeries figures have a name attribute, in the form: f-cc-nn, where cc is the chapter number containing the figure and nn is the consecutive numbering of the figure within the chapter, in this case it is f-16-14 meaning it is the forteenth figure in chapter 16.
This name attribute allows navigation to the table from any point in the Wiki where it is referenced (see below for the navigation link details).
Figures are always aligned in the centre of the page align="center".
The figure image itself occupies a single row of the table (first row) and for single images, the row only has one cell (a single column tables):
| Markdown |
|---|
|
|
<!-- Figure row --> <tr><td>
<!-- FIGURE --> <img width="600" src="./16-0000/02-images/figm-16-14.png" alt="Matilda the saluki">
</td></tr>
|
The image displayed as the Figure is within an <img> tag, the width attribute determines the size of the image (in this case the image is restricted to a maximum width of 600 pixels, width="600").
The src attributes gives (in this case) the relative path to the image, the image itself is the file: figm-16-125.png.
The alt text entry should always be used and give some textual description of the image (as a general rule of thumb, make the alt text the same as the figure caption text).
The figure row is followed by a caption row (this is the bit at the bottom of the figure that gives the figure number and description):
| Markdown |
|---|
|
|
<!-- CAPTION --> <tr><th align="center"><sup>
<!-- CAPTION TEXT --> Figure 16.14 — Matilda the saluki
</sup></th></tr>
|
The caption is very similar to the caption used in tables (see the previous section).
The caption cell is a heading cell <th> not <td>, this puts the caption in a bold font (saving the use of a <strong> tag).
The caption is always centred across the width of the table, hence the align="center".
Note
The figure is a contained in a table with a single column, hence there is no need for a 1colspan1 attribute
The caption is within a <sup>, superscript tag. This makes the text smaller than normal and give it a caption type appearance.
The caption text always has the form: Figure x.y — Description.
Where x and y are the chapter number and sequential figure number within the chapter (these are the same as the numbers given in the f-cc-nn name at the start of the table, but without leading zeros), in this case it is 16.15.
The — is an em dash (—) use to separate the table number from the description text.
The table terminates with a simple </table>
Note
There is no <br clear="all">* tag after the table; figures are always centred on the page and are not floating tables (see section 10.2.3 for details of floating elements).*
Each table should be preceded and followed by a blank line.
It is possible to add a link in the image table that allows the image to open in a new window (sort of).
This is the Markdown:
| Markdown and GitHub output | ||
|---|---|---|
|
|
||
<table name="f-16-14a" align="center"><!-- FIGURE START🔽🔽(BLANK LINE ABOVE) -->
<!-- Figure row --> <tr><td>
<!-- LINK --> <a href="./16-0000/02-images/fig-16-16.png" title="Use ctrl+click to open image in new tab">
<!-- FIGURE --> <img width="200" src="./16-0000/02-images/figm-16-16.png" alt="Adult Matilda">
</td></tr>
<!-- CAPTION --> <tr><th align="center"><sup>
<!-- CAPTION TEXT --> Figure 16.14a — Adult Matilda
</sup></th></tr>
</table> <!-- FIGURE END 🔼🔼(BLANK LINE BELOW) -->
| ||
|
|
||
| ||
| Table 16.18 — An image that opens in a new tab |
It has a link line above the <img> line
| Markdown |
|---|
|
|
<a href="./16-0000/02-images/fig-16-17.png" title="Use ctrl+click to open image in new tab">
|
The link itself href="./16-0000/02-images/fig-16-17.png" is identical to the src link for the image itself.
The title attribute for the link always has the text
Use ctrl+click to open image in new tab
This is an instruction that appears if the mouse hovers over the image. Pressing ctrl and clicking the image will open the image in a new browser tab.
The image that opens will be full size (or will have it's size restricted by the browser window size).
Important
It’s not actually possible to make GitHub open an image automatically in a new tab. This is the closest I could get.
Here’s a double image:
|
|
| Figure 16.15 — Matilda the puppy | Figure 16.16 — Matilda the adult |
|---|
She’s quite a pretty dog really.
The code is:
| Markdown |
|---|
|
|
<table align="center"><!-- DBL FIGURE START 🔽🔽(BLANK LINE ABOVE) -->
<!-- Figure row --> <tr>
<!-- FIGURE 1 ID --> <td name="f-16-15">
<!-- FIGURE 1 IMAGE --> <img width="300" src="./16-0000/02-images/figm-16-15.png" alt="Matilda the puppy">
</td>
<!-- FIGURE 2 ID --> <td name="f-16-16">
<!-- FIGURE 2 IMAGE --> <img width="300" src="./16-0000/02-images/figm-16-16.png" alt="Matilda the adult">
</td>
</tr>
<!-- CAPTION --> <tr>
<th align="center"><sup>
<!-- CAPTION TEXT 1 --> Figure 16.15 — Matilda the puppy
</sup></th>
<th align="center"><sup>
<!-- CAPTION TEXT 2 --> Figure 16.16 — Matilda the adult
</sup></th>
</tr>
</table> <!-- DBL FIGURE END🔼🔼(BLANK LINE BELOW) -->
|
| Table 16.19 — A PracticalSeries double figure |
This is basically the same table as before, just with two cells on each row (one for each image on the first row and one for each of the two captions on the second row).
The main difference between this and the single figure is that there are two name attributes and they have been moved to the <td> cells.
The reason for this is that it is not possible to give a tag multiple name attributes, i.e. The following wouldn’t work:
<table name="f-16-21" name="f-16-22" align="center">
By moving the name attributes to the <td> element, it allows navigation to either image to work.
These are very similar to the links to a table discussed in section 16.5.3.
The naming of each table figure that a link can be made to the figure from any page within the Wiki (or even from an external website).
Using the previous figure as an example, this had the name f-16-15. To link to this figure from a point within the same Wiki page, the link would be:
| Markdown and GitHub output |
|---|
|
|
This is a link to <a href="#f-16-15">Figure 16.15</a>.
|
|
|
|
This is a link to Figure 16.15. |
| Table 16.18 — Link to a figure |
If linking from a different page in the Wiki, the destination page must also be referenced, in this case it is on the this page, so the link becomes:
| Markdown |
|---|
|
|
This is a link to <a href="pagennn#f-16-15">Figure 16.15</a>.
|
The destination page is added prior to the #.
Finally, to link to the table from an external website, the full URL for the Wiki page must be used, in this case it is:
| Markdown |
|---|
|
|
This is a link to <a href="https://github.com/practicalseries/GitHub-Wiki-Design-and-Implementation/
wiki/pagennn#f-16-15">Figure 16.15</a>.
|
A full discussion of these types of links is given in section 9.5.
I don’t like the lists that are available via Markdown or HTML (see section 8.2 & 8.3), they are too simplistic and they don’t look very good:
|
|
| An ordered (numbered) list | An unordered (unnumbered) list |
|---|
The PracticalSeries supports more “exciting” lists, here’s some examples:
|
| List c.n — PS Basic unordered |
|---|
|
| List c.n — PS Basic ordered |
|---|
| |
|
|
| |
|
|
| |
| List c.n — PS mixed, basic list | |
|---|---|
| ● | MainPoint |
| ● | MainPoint |
| ● | MainPoint |
| ● | MainPoint |
| ● | MainPoint |
| ● | MainPoint |
| ● | MainPoint |
| ● | MainPoint |
| ● | MainPoint |
| ● | MainPoint |
| List c.n — PS unnumberd 2-column list |
|---|
| ① | MainPoint |
| ② | MainPoint |
| ③ | MainPoint |
| ④ | MainPoint |
| ⑤ | MainPoint |
| ⑥ | MainPoint |
| ⑦ | MainPoint |
| ⑧ | MainPoint |
| ⑨ | MainPoint |
| ⑩ | MainPoint |
| List c.n — PS indexed 2-column list |
|---|
| ❶ | MainPoint |
| ❷ | MainPoint |
| ❸ | MainPoint |
| ❹ | MainPoint |
| ❺ | MainPoint |
| ❻ | MainPoint |
| ❼ | MainPoint |
| ❽ | MainPoint |
| ❾ | MainPoint |
| ❿ | MainPoint |
| List c.n — PS Reversed indexed 2-column list |
|---|
|
① MainPoint ② MainPoint | |
|
|
|
③ MainPoint ④ MainPoint | |
|
|
|
⑤ MainPoint ⑥ MainPoint ⑦ MainPoint ⑧ MainPoint ⑨ MainPoint ⑩ MainPoint | |
| List c.n — PS mixed indexed list | |
|---|---|
|
❶ MainPoint ❷ MainPoint | |
|
|
|
❸ MainPoint ❹ MainPoint | |
|
|
|
❺ MainPoint ❻ MainPoint ❼ MainPoint ❽ MainPoint ❾ MainPoint ❿ MainPoint | |
| List c.n — PS mixed reverse indexed list | |
|---|---|
Task lists are catered for too:
|
⭕ MainPoint ✅ MainPoint ⭕ MainPoint ✅ MainPoint ⭕ MainPoint | |
|---|---|
|
✅ Subpoint ⭕ Subpoint ✅ Subpoint ⭕ Subpoint ✅ Subpoint |
|
| List c.n — PS task list | |
| Points and subpoints | Observations | |
|---|---|---|
|
⭕ MainPoint ✅ MainPoint ⭕ MainPoint ✅ MainPoint ⭕ MainPoint |
Observation Observation Observation Observation Observation |
|
|
✅ Subpoint ⭕ Subpoint ✅ Subpoint ⭕ Subpoint ✅ Subpoint |
Observation Observation Observation Observation Observation |
|
| List c.n — PS enhanced task list | ||
The one thing all these lists have in common is that they are all contained within tables.
I think it is fair to say that this list looks better than a default GitHub list.
The default lists don’t stand out enough, putting it in a table applies more emphasis to the table and allows them to become navigable objects.
The following sections go through the various PracticalSeries list formats, some are easy to use, others are more esoteric and don’t self-number.
I go through each in turn (unfortunately, there are quite a few of them). Each starts with an example showing how the list appears on a page, ignore the ones you don’t like.
The terminology I use is this: mixed lists have a combination of ordered and unnumbered lists, indexed lists use numbers in circles (①, ②, ③ &c.), reverse index have numbers in a black circle (❶, ❷, ❸ &c.). Task lists have either a tick ✅ or a circle ⭕.
All lists discussed here are contained within a HTML table, in fact the lists themselves are also in HTML format (this is necessary, it is not possible to use Markdown within a HTML table).
All the lists are within a <table> tag with a name attribute, the list table is always centred on the page align="center".
| Markdown |
|---|
|
|
<table name="l-cc-nn" align="center"> <!-- LIST START🔽🔽(BLANK LINE ABOVE) -->
|
| Table 16.20 — Common points for lists |
All PracticalSeries lists (like tables and figures) have a name attribute, in the form: l-cc-nn, where cc is the chapter number containing the list and nn is the consecutive numbering of the list within the chapter, example l-01-05 meaning it is the fifth list in chapter 1.
These lists can be linked to in exactly the same way as that for tables and figures discussed in the previous sections.
Lists are either one, two or three columns wide, the width of each column is set at some point within the table by the width attribute (usually in the caption area and sometimes in the heading area). The width attribute is contained with a <td> or <th> tag and sets the width of the column in pixels.
**Generally, each point within a list should fit on a single line (without wrapping onto the next line), there are some lists that specifically manage wrapped text, but for most lists, stick to one line.
The lists are largely similar in construction, the first list below covers the main points of a list, subsequent lists explain the differences.
|
| List 16.5 — PS basic unordered list |
|---|
This is the simplest of the PracticalSeries lists, the code is:
| Markdown |
|---|
|
|
<table name="l-16-05" align="center"> <!-- LIST START🔽🔽(BLANK LINE ABOVE) -->
<!-- UNORD LIST --> <tr><td><ul>
<li>  <!-- TEXT -->UnorderedPoint</li>
<li>  <!-- TEXT -->UnorderedPoint</li>
<li>  <!-- TEXT -->UnorderedPoint</li>
<li>  <!-- TEXT -->UnorderedPoint</li>
<li>  <!-- TEXT -->UnorderedPoint</li>
<!-- END OF LIST --> </ul></td></tr>
<!-- CAPTION --> <tr>
<!-- LIST WIDTH --> <th align="left" width="400">     <sup>
<!-- CAPTION TEXT -->List 16.5 — PS basic unordered list
</sup></th></tr>
</table> <!-- LIST END 🔼🔼(BLANK LINE BELOW) -->
|
| Table 16.21 — PS basic unordered list code |
The unordered list is within a one column, 2 row table. The first row contains the individual points in the list (the UnorderedPoint in the above code), these should be changed to reflect the required points in the list. Lines can be deleted or added as required.
The list itself is within with the <ul> unordered list HMTL tag, and each entry in the list is within its own <li> list tag, see section 8.2.
The text of each point within the list (the UnorderedPoint text in the above code), is indented by two em-spaces, these add whitespace between the point character and the text, it just makes things look nicer.
The second row of the table contains the list caption (a list number followed by a descriptive text)
The caption is very similar to the caption used in tables (see section 16.5.3).
The caption is indented by several space characters, to make the text align with the text of the individual list points (again, just to make the thing look better).
Other points in the caption are comparible with table captions, again see section 16.5.3.
The width of the table must be specified and must be wide enough that each point within the list does not wrap onto a second line. The width of the table is set in the <th> tag of the caption with the width="400" attribute. In this case the table is set to a width of 400 pixels.
|
| List 16.6 — PS basic ordered list |
|---|
The code is:
| Markdown |
|---|
|
|
<table name="l-16-06" align="center"> <!-- LIST START🔽🔽(BLANK LINE ABOVE) -->
<!-- ORD LIST --> <tr><td><ol start="1">
<li>  <!-- TEXT -->OrderedPoint</li>
<li>  <!-- TEXT -->OrderedPoint</li>
<li>  <!-- TEXT -->OrderedPoint</li>
<li>  <!-- TEXT -->OrderedPoint</li>
<li>  <!-- TEXT -->OrderedPoint</li>
<!-- END OF LIST --> </ol></td></tr>
<!-- CAPTION --> <tr>
<!-- LIST WIDTH --> <th align="left" width="400">     <sup>
<!-- CAPTION TEXT -->List 16.6 — PS basic ordered list
</sup></th></tr>
</table> <!-- LIST END 🔼🔼(BLANK LINE BELOW) -->
<!-- LIST END 🔼🔼(BLANK LINE BELOW) -->
|
| Table 16.22 — PS basic ordered list code |
This is identical to the unordered list of the previous section with the exception of using the ordered list tag <ol> in place of the unordered tag <ul>. Change the start value to renumber the list (by default, it is set to 1).
Again the width of the table must be set in the caption <th> tag.
| |
|
|
| |
|
|
| |
| List 16.7 — PS mixed ordered and unordered lists | |
|---|---|
This is a mixture of ordered (numbered) list points and unorder list points, referred to here a “staged” list.
The list is in a two column, multiple row table.
The main points are ordered (numbered) and span both columns in a row, the unordered sub-points (unnumbered) are in the second column of the next row down (generally, main points are in an unshaded row and sub-points in the shaded rows).
The width of the first column is fixed and is arranged such that the point character of the sub-points aligns with the text of the main points.
The code is:
| Markdown |
|---|
|
|
<table name="l-16-07" align="center"> <!-- LIST START🔽🔽(BLANK LINE ABOVE) -->
<!-- MAIN LIST - START --><tr><td colspan="2"><ol start="1">
<li>  <!-- TEXT -->MainPoint</li>
<li>  <!-- TEXT -->MainPoint</li>
<!-- END OF MAIN LIST --> </ol></td></tr>
<!-- SUB LIST - START --> <tr><td></td><td><ul>
<li>  <!-- TEXT -->SubPoint</li>
<li>  <!-- TEXT -->SubPoint</li>
<!-- END OF SUB LIST --> </ul></td></tr>
<!-- MAIN LIST - START --><tr><td colspan="2"><ol start="3">
<li>  <!-- TEXT -->MainPoint</li>
<li>  <!-- TEXT -->MainPoint</li>
<!-- END OF MAIN LIST --> </ol></td></tr>
<!-- SUB LIST - START --> <tr><td></td><td><ul>
<li>  <!-- TEXT -->SubPoint</li>
<li>  <!-- TEXT -->SubPoint</li>
<!-- END OF SUB LIST --> </ul></td></tr>
<!-- MAIN LIST - START --><tr><td colspan="2"><ol start="5">
<li>  <!-- TEXT -->MainPoint</li>
<li>  <!-- TEXT -->MainPoint</li>
<!-- END OF MAIN LIST --> </ol></td></tr>
<!-- CAPTION --> <tr><th width="52"></th><!-- SPACER -->
<!-- LIST WIDTH --> <th align="left" width="400"><sup>
<!-- CAPTION TEXT --> <!-- TEXT -->List 16.7 — PS mixed ordered and unordered lists
</sup></th></tr>
</table> <!-- LIST END 🔼🔼(BLANK LINE BELOW) -->
|
| Table 16.23 — PS basic unordered list code |
The main points are all ordered lists <ol> that span both columns of the table colspan="2", as follows:
| Markdown |
|---|
|
|
<!-- MAIN LIST - START --><tr><td colspan="2"><ol start="1">
<li>  <!-- TEXT -->MainPoint</li>
<li>  <!-- TEXT -->MainPoint</li>
<!-- END OF MAIN LIST --> </ol></td></tr>
|
Again, each numbered point MainPoint is in its own <li> tag, add and remove lines as required.
The starting number for each main list is specified in the start="1" attribute, these have to be set for each set of main points in the list (1, 3 and 5 in this case).
The sub-points are just unordered lists <ul>. Again add and remove as necessary.
| Markdown |
|---|
|
|
<!-- SUB LIST - START --> <tr><td></td><td><ul>
<li>  <!-- TEXT -->SubPoint</li>
<li>  <!-- TEXT -->SubPoint</li>
<!-- END OF SUB LIST --> </ul></td></tr>
|
The caption is very similar to the caption used in the previous lists, in this case there are two columns, the first is set to a fixed width of 52 pixels. The second is set to give the required width of the list table.
|
||
|
||
|
||
|
||
|
||
| List 16.8 — PS mixed ordered and unordered lists | ||
|---|---|---|
This is very similar to the previous list; it just has a blank column to the left to give additional indentation to the list.
| Markdown |
|---|
|
|
<table name="l-16-08" align="center"> <!-- LIST START🔽🔽(BLANK LINE ABOVE) -->
<!-- MAIN LIST - START --><tr><td></td><!-- first cell is empty (spacer) -->
<!-- MAIN LIST - NUMBER --> <td colspan="2"><ol start="1">
<li>  <!-- TEXT -->MainPoint</li>
<li>  <!-- TEXT -->MainPoint</li>
<!-- END OF MAIN LIST --> </ol></td></tr>
<!-- SUB LIST - START --> <tr><td colspan="2"></td><td><ul><!-- Entry in third column -->
<li>  <!-- TEXT -->SubPoint</li>
<li>  <!-- TEXT -->SubPoint</li>
<!-- END OF SUB LIST --> </ul></td></tr>
<!-- MAIN LIST - START --><tr><td></td> <!-- first cell is empty (spacer) -->
<!-- MAIN LIST - NUMBER --> <td colspan="2"><ol start="3">
<li>  <!-- TEXT -->MainPoint</li>
<li>  <!-- TEXT -->MainPoint</li>
<!-- END OF MAIN LIST --> </ol></td></tr>
<!-- SUB LIST - START --> <tr><td colspan="2"></td><td><ul><!-- Entry in third column -->
<li>  <!-- TEXT -->SubPoint</li>
<li>  <!-- TEXT -->SubPoint</li>
<!-- END OF SUB LIST --> </ul></td></tr>
<!-- MAIN LIST - START --><tr><td></td> <!-- first cell is empty (spacer) -->
<!-- MAIN LIST - NUMBER --> <td colspan="2"><ol start="5">
<li>  <!-- TEXT -->MainPoint</li>
<li>  <!-- TEXT -->MainPoint</li>
<!-- END OF MAIN LIST --> </ol></td></tr>
<!-- CAPTION --> <tr><th width="50"></th><th width="52"></th><!-- SPACERS -->
<!-- LIST WIDTH --> <th align="left" width="400"><sup>
<!-- CAPTION TEXT --> <!-- TEXT -->List 16.8 — PS mixed ordered and unordered lists
</sup></th></tr>
</table> <!-- LIST END 🔼🔼(BLANK LINE BELOW) -->
|
| Table 16.24 — PS basic unordered list code |
Refer to the previous table for instructions, the main difference is that the first line of the caption sets the width for the first two columns, these are fixed at 50 pixels and 52 pixels.
|
① MainPoint ② MainPoint ③ MainPoint ④ MainPoint ⑤ MainPoint ⑥ MainPoint ⑦ MainPoint ⑧ MainPoint ⑨ MainPoint ⑩ MainPoint ⑪ MainPoint ⑫ MainPoint ⑬ MainPoint ⑭ MainPoint ⑮ MainPoint ⑯ MainPoint ⑰ MainPoint ⑱ MainPoint ⑲ MainPoint ⑳ MainPoint |
| List 16.9 — PS Index list |
|---|
This isn’t actually a list at all (and in truth I’m not the biggest fan of it, the numbers are too small — the reverse index is better, it has larger numbers, see below), it is a series of circled numbers that are entered individually (there is no automatic numbering) to create the list.
There are only 20 of these numbers in circles (there are actually some more, all the way up to fifty I think, but after 20 the numbers changes size and the list looks silly).
The code is this (this is for all 20 numbers):
| Markdown |
|---|
|
|
<table name="l-16-09" align="center"> <!-- LIST START🔽🔽(BLANK LINE ABOVE) -->
<!-- INDEXED LIST --> <tr><td>
 ①<!-- 1 -->  <!-- TEXT -->MainPoint<br>
 ②<!-- 2 -->  <!-- TEXT -->MainPoint<br>
 ③<!-- 3 -->  <!-- TEXT -->MainPoint<br>
 ④<!-- 4 -->  <!-- TEXT -->MainPoint<br>
 ⑤<!-- 5 -->  <!-- TEXT -->MainPoint<br>
 ⑥<!-- 6 -->  <!-- TEXT -->MainPoint<br>
 ⑦<!-- 7 -->  <!-- TEXT -->MainPoint<br>
 ⑧<!-- 8 -->  <!-- TEXT -->MainPoint<br>
 ⑨<!-- 9 -->  <!-- TEXT -->MainPoint<br>
 ⑩<!-- 10 -->  <!-- TEXT -->MainPoint<br>
 ⑪<!-- 11 -->  <!-- TEXT -->MainPoint<br>
 ⑫<!-- 12 -->  <!-- TEXT -->MainPoint<br>
 ⑬<!-- 13 -->  <!-- TEXT -->MainPoint<br>
 ⑭<!-- 14 -->  <!-- TEXT -->MainPoint<br>
 ⑮<!-- 15 -->  <!-- TEXT -->MainPoint<br>
 ⑯<!-- 16 -->  <!-- TEXT -->MainPoint<br>
 ⑰<!-- 17 -->  <!-- TEXT -->MainPoint<br>
 ⑱<!-- 18 -->  <!-- TEXT -->MainPoint<br>
 ⑲<!-- 19 -->  <!-- TEXT -->MainPoint<br>
 ⑳<!-- 20 -->  <!-- TEXT -->MainPoint<br>
<!-- END OF LIST --> </td></tr>
<!-- CAPTION --> <tr>
<!-- LIST WIDTH --> <th align="left" width="400">     <sup>
<!-- CAPTION TEXT -->List 16.9 — PS Index list
</sup></th></tr>
</table> <!-- LIST END 🔼🔼(BLANK LINE BELOW) -->
|
| Table 16.25 — PS Index list code |
It is very similar to the basic ordered list, but doesn’t have an ordered list tag <ol> and the entries are not within <li> tags.
Instead the entire list is constructed using the Unicode escape sequences, here ① corresponds to the character ① and ⑳ corresponds to the character ⑳.
|
❶ MainPoint ❷ MainPoint ❸ MainPoint ❹ MainPoint ❺ MainPoint ❻ MainPoint ❼ MainPoint ❽ MainPoint ❾ MainPoint ❿ MainPoint |
| List 16.10 — PS reverse index list |
|---|
This looks better than the indexed list, the numbers are larger and more readable.
The downside is that there are only ten such numbers, so the list can’t be more than 10 points long: This is the code, the only difference between this and the indexed link are the Unicode characters and the spacing characters.
| Markdown |
|---|
|
|
<table name="l-16-10" align="center"><!-- LIST START🔽🔽(BLANK LINE ABOVE) -->
<!-- INDEXED LIST --> <tr><td>
 ❶<!-- 1 -->   <!-- TEXT -->MainPoint<br>
 ❷<!-- 2 -->   <!-- TEXT -->MainPoint<br>
 ❸<!-- 3 -->   <!-- TEXT -->MainPoint<br>
 ❹<!-- 4 -->   <!-- TEXT -->MainPoint<br>
 ❺<!-- 5 -->   <!-- TEXT -->MainPoint<br>
 ❻<!-- 6 -->   <!-- TEXT -->MainPoint<br>
 ❼<!-- 7 -->   <!-- TEXT -->MainPoint<br>
 ❽<!-- 8 -->   <!-- TEXT -->MainPoint<br>
 ❾<!-- 9 -->   <!-- TEXT -->MainPoint<br>
 ❿<!-- 10 -->   <!-- TEXT -->MainPoint<br>
<!-- END OF LIST --> </td></tr>
<!-- CAPTION --> <tr>
<!-- LIST WIDTH --> <th align="left" width="400">     <sup> 
<!-- CAPTION TEXT -->List 16.10 — PS reverse index list
</sup></th></tr>
</table> <!-- LIST END 🔼🔼(BLANK LINE BELOW) -->
|
| Table 16.26 — PS reverse indexed list code |
| ① | MainPoint lorem ipsum dolor sit amet, consectetur adipiscing elit. |
| ② | MainPoint |
| ③ | MainPoint |
| ④ | MainPoint |
| ⑤ | MainPoint |
| ⑥ | MainPoint |
| ⑦ | MainPoint |
| ⑧ | MainPoint |
| ⑨ | MainPoint |
| ⑩ | MainPoint |
| ⑪ | MainPoint |
| ⑫ | MainPoint |
| ⑬ | MainPoint |
| ⑭ | MainPoint |
| ⑮ | MainPoint |
| ⑯ | MainPoint |
| ⑰ | MainPoint |
| ⑱ | MainPoint |
| ⑲ | MainPoint |
| ⑳ | MainPoint |
| List 16.11 — PS index list with text wrap |
|---|
This list has two columns per index number, the first column contains the point number and is vertically aligned (number is always at the top).
The second column contains the text for the ordered point, because this is a separate column, the text can be allowed to wrap without interfering with subsequent rows (as shown in point ①)
| Markdown |
|---|
|
|
<table name="l-16-11" align="center"> <!-- LIST START🔽🔽(BLANK LINE ABOVE) -->
<!-- LIST ROW 01 --><tr><td valign="top">①<!-- 1 --></td>
<td><!-- TEXT -->MainPoint lorem ipsum dolor sit amet, consectetur adipiscing elit.</td></tr>
<!-- LIST ROW 02 --><tr><td valign="top">②<!-- 2 --></td>
<td><!-- TEXT -->MainPoint</td></tr>
<!-- LIST ROW 03 --><tr><td valign="top">③<!-- 3 --></td>
<td><!-- TEXT -->MainPoint</td></tr>
<!-- LIST ROW 04 --><tr><td valign="top">④<!-- 4 --></td>
<td><!-- TEXT -->MainPoint</td></tr>
<!-- LIST ROW 05 --><tr><td valign="top">⑤<!-- 5 --></td>
<td><!-- TEXT -->MainPoint</td></tr>
<!-- LIST ROW 06 --><tr><td valign="top">⑥<!-- 6 --></td>
<td><!-- TEXT -->MainPoint</td></tr>
<!-- LIST ROW 07 --><tr><td valign="top">⑦<!-- 7 --></td>
<td><!-- TEXT -->MainPoint</td></tr>
<!-- LIST ROW 08 --><tr><td valign="top">⑧<!-- 8 --></td>
<td><!-- TEXT -->MainPoint</td></tr>
<!-- LIST ROW 09 --><tr><td valign="top">⑨<!-- 9 --></td>
<td><!-- TEXT -->MainPoint</td></tr>
<!-- LIST ROW 10 --><tr><td valign="top">⑩<!-- 10 --></td>
<td><!-- TEXT -->MainPoint</td></tr>
<!-- LIST ROW 11 --><tr><td valign="top">⑪<!-- 11 --></td>
<td><!-- TEXT -->MainPoint</td></tr>
<!-- LIST ROW 12 --><tr><td valign="top">⑫<!-- 12 --></td>
<td><!-- TEXT -->MainPoint</td></tr>
<!-- LIST ROW 13 --><tr><td valign="top">⑬<!-- 13 --></td>
<td><!-- TEXT -->MainPoint</td></tr>
<!-- LIST ROW 14 --><tr><td valign="top">⑭<!-- 14 --></td>
<td><!-- TEXT -->MainPoint</td></tr>
<!-- LIST ROW 15 --><tr><td valign="top">⑮<!-- 15 --></td>
<td><!-- TEXT -->MainPoint</td></tr>
<!-- LIST ROW 16 --><tr><td valign="top">⑯<!-- 16 --></td>
<td><!-- TEXT -->MainPoint</td></tr>
<!-- LIST ROW 17 --><tr><td valign="top">⑰<!-- 17 --></td>
<td><!-- TEXT -->MainPoint</td></tr>
<!-- LIST ROW 18 --><tr><td valign="top">⑱<!-- 18 --></td>
<td><!-- TEXT -->MainPoint</td></tr>
<!-- LIST ROW 19 --><tr><td valign="top">⑲<!-- 19 --></td>
<td><!-- TEXT -->MainPoint</td></tr>
<!-- LIST ROW 20 --><tr><td valign="top">⑳<!-- 20 --></td>
<td><!-- TEXT -->MainPoint</td></tr>
<!-- CAPTION --> <tr><th width="52"></th><!-- SPACER -->
<!-- LIST WIDTH --> <th align="left" width="348"><sup>
<!-- CAPTION TEXT --><!-- TEXT -->List 16.11 — PS index list with text wrap<
</sup></th></tr>
</table> <!-- LIST END 🔼🔼(BLANK LINE BELOW) -->
|
| Table 16.27 — PS index list with text wrap |
| ❶ | MainPoint lorem ipsum dolor sit amet, consectetur adipiscing elit. |
| ❷ | MainPoint |
| ❸ | MainPoint |
| ❹ | MainPoint |
| ❺ | MainPoint |
| ❻ | MainPoint |
| ❼ | MainPoint |
| ❽ | MainPoint |
| ❾ | MainPoint |
| ❿ | MainPoint |
| List 16.12 — PS reverse index list with text wrap |
|---|
This is identical to the previous list, but uses the reverse index characters. There are only 10 such characters, hence the list cannot have more than 10 points
| Markdown |
|---|
|
|
<table name="l-16-12" align="center"> <!-- LIST START🔽🔽(BLANK LINE ABOVE) -->
<!-- LIST ROW 01 --><tr><td valign="top">❶<!-- 1 --></td>
<td><!-- TEXT -->MainPoint</td></tr>
<!-- LIST ROW 02 --><tr><td valign="top">❷<!-- 2 --></td>
<td><!-- TEXT -->MainPoint</td></tr>
<!-- LIST ROW 03 --><tr><td valign="top">❸<!-- 3 --></td>
<td><!-- TEXT -->MainPoint</td></tr>
<!-- LIST ROW 04 --><tr><td valign="top">❹<!-- 4 --></td>
<td><!-- TEXT -->MainPoint</td></tr>
<!-- LIST ROW 05 --><tr><td valign="top">❺<!-- 5 --></td>
<td><!-- TEXT -->MainPoint</td></tr>
<!-- LIST ROW 06 --><tr><td valign="top">❻<!-- 6 --></td>
<td><!-- TEXT -->MainPoint</td></tr>
<!-- LIST ROW 07 --><tr><td valign="top">❼<!-- 7 --></td>
<td><!-- TEXT -->MainPoint</td></tr>
<!-- LIST ROW 08 --><tr><td valign="top">❽<!-- 8 --></td>
<td><!-- TEXT -->MainPoint</td></tr>
<!-- LIST ROW 09 --><tr><td valign="top">❾<!-- 9 --></td>
<td><!-- TEXT -->MainPoint</td></tr>
<!-- LIST ROW 10 --><tr><td valign="top">❿<!-- 10 --></td>
<td><!-- TEXT -->MainPoint</td></tr>
<!-- CAPTION --> <tr><th width="52"></th><!-- SPACER -->
<!-- LIST WIDTH --> <th align="left" width="348"><sup>
<!-- CAPTION TEXT --><!-- TEXT -->List 16.12 — PS reverse index list with text wrap
</sup></th></tr>
</table> <!-- LIST END 🔼🔼(BLANK LINE BELOW) -->
|
| Table 16.28 — PS index list with text wrap |
|
① MainPoint ② MainPoint | |
|
|
|
③ MainPoint ④ MainPoint | |
|
|
|
⑤ MainPoint ⑥ MainPoint ⑦ MainPoint ⑧ MainPoint ⑨ MainPoint ⑩ MainPoint ⑪ MainPoint ⑫ MainPoint ⑬ MainPoint ⑭ MainPoint ⑮ MainPoint ⑯ MainPoint ⑰ MainPoint ⑱ MainPoint ⑲ MainPoint ⑳ MainPoint | |
| List 16.13 — PS indexed, mixed list | |
|---|---|
This is a combination of the index list and the staged list
The code is similar except that the main point lists are replaced with the reverse index lists
| Markdown |
|---|
|
|
<table name="l-16-13" align="center"> <!-- LIST START🔽🔽(BLANK LINE ABOVE) -->
<!-- MAIN LIST - START --><tr><td colspan="2">
 ①<!-- 1 -->  <!-- TEXT -->MainPoint<br>
 ②<!-- 2 -->  <!-- TEXT -->MainPoint<br>
<!-- END OF MAIN LIST --> </td></tr>
<!-- SUB LIST - START --> <tr><td></td><td><ul>
<li>  <!-- TEXT -->SubPoint</li>
<li>  <!-- TEXT -->SubPoint</li>
<!-- END OF SUB LIST --> </ul></td></tr>
<!-- MAIN LIST - START --><tr><td colspan="2">
 ③<!-- 3 -->  <!-- TEXT -->MainPoint<br>
 ④<!-- 4 -->  <!-- TEXT -->MainPoint<br>
<!-- END OF MAIN LIST --> </td></tr>
<!-- SUB LIST - START --> <tr><td></td><td><ul>
<li>  <!-- TEXT -->SubPoint</li>
<li>  <!-- TEXT -->SubPoint</li>
<!-- END OF SUB LIST --> </ul></td></tr>
<!-- MAIN LIST - START --><tr><td colspan="2">
 ⑤<!-- 5 -->  <!-- TEXT -->MainPoint<br>
 ⑥<!-- 6 -->  <!-- TEXT -->MainPoint<br>
 ⑦<!-- 7 -->  <!-- TEXT -->MainPoint<br>
 ⑧<!-- 8 -->  <!-- TEXT -->MainPoint<br>
 ⑨<!-- 9 -->  <!-- TEXT -->MainPoint<br>
 ⑩<!-- 10 -->  <!-- TEXT -->MainPoint<br>
 ⑪<!-- 11 -->  <!-- TEXT -->MainPoint<br>
 ⑫<!-- 12 -->  <!-- TEXT -->MainPoint<br>
 ⑬<!-- 13 -->  <!-- TEXT -->MainPoint<br>
 ⑭<!-- 14 -->  <!-- TEXT -->MainPoint<br>
 ⑮<!-- 15 -->  <!-- TEXT -->MainPoint<br>
 ⑯<!-- 16 -->  <!-- TEXT -->MainPoint<br>
 ⑰<!-- 17 -->  <!-- TEXT -->MainPoint<br>
 ⑱<!-- 18 -->  <!-- TEXT -->MainPoint<br>
 ⑲<!-- 19 -->  <!-- TEXT -->MainPoint<br>
 ⑳<!-- 20 -->  <!-- TEXT -->MainPoint<br>
<!-- END OF MAIN LIST --> </td></tr>
<!-- CAPTION --> <tr><th width="52"></th><!-- SPACER -->
<!-- LIST WIDTH --> <th align="left" width="300"><sup>
<!-- CAPTION TEXT --> <!-- TEXT -->List 16.13 — PS indexed, mixed list
</sup></th></tr>
</table> <!-- LIST END 🔼🔼(BLANK LINE BELOW) -->
|
| Table 16.29 — PS indexed, mixed list |
|
❶ MainPoint ❷ MainPoint | |
|
|
|
❸ MainPoint ❹ MainPoint | |
|
|
|
❺ MainPoint ❻ MainPoint ❼ MainPoint ❽ MainPoint ❾ MainPoint ❿ MainPoint | |
| List 16.14 — PS reverse indexed, mixed list | |
|---|---|
This is identical to the previous list, but uses the reverse index characters (of which there are only 10).
| Markdown |
|---|
|
|
<table name="l-16-14" align="center"> <!-- LIST START🔽🔽(BLANK LINE ABOVE) -->
<!-- MAIN LIST - START --><tr><td colspan="2">
 ❶<!-- 1 -->   <!-- TEXT -->MainPoint<br>
 ❷<!-- 2 -->   <!-- TEXT -->MainPoint<br>
<!-- END OF MAIN LIST --> </td></tr>
<!-- SUB LIST - START --> <tr><td></td><td><ul>
<li>  <!-- TEXT -->SubPoint</li>
<li>  <!-- TEXT -->SubPoint</li>
<!-- END OF SUB LIST --> </ul></td></tr>
<!-- MAIN LIST - START --><tr><td colspan="2">
 ❸<!-- 3 -->   <!-- TEXT -->MainPoint<br>
 ❹<!-- 4 -->   <!-- TEXT -->MainPoint<br>
<!-- END OF MAIN LIST --> </td></tr>
<!-- SUB LIST - START --> <tr><td></td><td><ul>
<li>  <!-- TEXT -->SubPoint</li>
<li>  <!-- TEXT -->SubPoint</li>
<!-- END OF SUB LIST --> </ul></td></tr>
<!-- MAIN LIST - START --><tr><td colspan="2">
 ❺<!-- 5 -->   <!-- TEXT -->MainPoint<br>
 ❻<!-- 6 -->   <!-- TEXT -->MainPoint<br>
 ❼<!-- 7 -->   <!-- TEXT -->MainPoint<br>
 ❽<!-- 8 -->   <!-- TEXT -->MainPoint<br>
 ❾<!-- 9 -->   <!-- TEXT -->MainPoint<br>
 ❿<!-- 10 -->   <!-- TEXT -->MainPoint<br>
<!-- END OF MAIN LIST --> </td></tr>
<!-- CAPTION --> <tr><th width="52"></th><!-- SPACER -->
<!-- LIST WIDTH --> <th align="left" width="300"><sup>
<!-- CAPTION TEXT --> <!-- TEXT -->List 16.14 — PS reverse indexed, mixed list
</sup></th></tr>
</table> <!-- LIST END 🔼🔼(BLANK LINE BELOW) -->
<!-- LIST END 🔼🔼(BLANK LINE BELOW) -->
|
| Table 16.30 — PS indexed, mixed list |
|
⭕ MainPoint ✅ MainPoint ⭕ MainPoint ✅ MainPoint ⭕ MainPoint | |
|---|---|
|
✅ Subpoint ⭕ Subpoint ✅ Subpoint ⭕ Subpoint ✅ Subpoint |
|
| List 16.15 — PS task list | |
The task list is a two-column table constructed using emoji characters for the red circles ⭕ and green ticks ✅.
The construction is very similar to the indexed, mixed lists, except that sub-points (like the main points of the indexed list) have no list tags <ul> or <li>.
To mark a task as complete, simply replace the circle emojis with the ticked emoji. There is a copy of both in the comment field of the first <table> tag.
| Markdown |
|---|
|
|
<table name="l-16-15" align="center"><!-- TASK LIST START🔽🔽(BLANK LINE ABOVE) ⭕✅-->
<!-- MAIN LIST --> <tr><th colspan="2" align="left">
⭕  <!-- TEXT -->MainPoint<br>
✅  <!-- TEXT -->MainPoint<br>
⭕  <!-- TEXT -->MainPoint<br>
✅  <!-- TEXT -->MainPoint<br>
⭕  <!-- TEXT -->MainPoint<br>
<!-- END OF MAIN --> </th></tr>
<!-- SUBLIST --> <tr><td></td><td>
✅  <!-- TEXT -->Subpoint<br>
⭕  <!-- TEXT -->Subpoint<br>
✅  <!-- TEXT -->Subpoint<br>
⭕  <!-- TEXT -->Subpoint<br>
✅  <!-- TEXT -->Subpoint<br>
<!-- END OF SUBLIST --></td></tr>
<!-- CAPTION --> <tr><th width="52"></th><!-- SPACER -->
<!-- LIST WIDTH --> <th align="left" width="348"><sup> 
<!-- CAPTION TEXT -->List 16.15 — PS task list
</sup></th></tr>
</table> <!-- TASK LIST END 🔼🔼(BLANK LINE BELOW) -->
|
| Table 16.31 — PS task list code |
| Points/subpoints | Observations | |
|---|---|---|
|
⭕ MainPoint ✅ MainPoint ⭕ MainPoint ✅ MainPoint ⭕ MainPoint |
Observation Observation Observation Observation Observation |
|
|
✅ Subpoint ⭕ Subpoint ✅ Subpoint ⭕ Subpoint ✅ Subpoint |
Observation Observation Observation Observation Observation |
|
| List 16.16 — PS enhanced task list with observations | ||
The task list is a three-column table constructed using emoji characters for the red circles ⭕ and green ticks ✅.
The construction is very similar to the indexed, mixed lists, except that sub-points (like the main points of the indexed list) have no list tags <ul> or <li>.
To mark a task as complete, simply replace the circle emojis with the ticked emoji. There is a copy of both in the comment field of the first <table> tag.
The third column in the list table allows observations to be entered.
| Markdown |
|---|
|
|
<table name="l-16-16" align="center"><!-- TASK LIST START🔽🔽(BLANK LINE ABOVE) ⭕✅-->
<tr><th width="52"></th><th align="left" width="174">Points/subpoints</th>
<th align="left" width="174">Observations</th></tr>
<!-- MAIN LIST --> <tr><th colspan="2" align="left">
⭕  <!-- TEXT -->MainPoint<br>
✅  <!-- TEXT -->MainPoint<br>
⭕  <!-- TEXT -->MainPoint<br>
✅  <!-- TEXT -->MainPoint<br>
⭕  <!-- TEXT -->MainPoint<br>
<!-- END OF POINTS --> </th>
<!-- OBSERVATIONS --> <td>
Observation<br>
Observation<br>
Observation<br>
Observation<br>
Observation<br>
<!-- END OF OBS --> </td>
<!-- END OF MAIN --> </tr>
<!-- SUBLIST --> <tr><td></td><td>
✅  <!-- TEXT -->Subpoint<br>
⭕  <!-- TEXT -->Subpoint<br>
✅  <!-- TEXT -->Subpoint<br>
⭕  <!-- TEXT -->Subpoint<br>
✅  <!-- TEXT -->Subpoint<br>
<!-- END OF SUBLIST --></td></td>
<!-- OBSERVATIONS --> <td>
Observation<br>
Observation<br>
Observation<br>
Observation<br>
Observation<br>
<!-- END OF OBS --> </td>
<!-- END OF MAIN --> </tr>
<!-- CAPTION --> <tr><th></th><!-- SPACER -->
<th align="left" colspan="2"><sup> 
<!-- CAPTION TEXT -->List 16.16 — PS enhanced task list with observations
</sup></th></tr>
</table> <!-- TASK LIST END 🔼🔼(BLANK LINE BELOW) -->
|
| Table 16.32 — PS enhanced task list with observations code |
The main difference here is the addition of the observation cells (one for main points, one for sub-points).
This table has a header row at the top, the widths of each column is set in this header row rather than in the caption row at the bottom.
Code fragments are fairly easy, they generally use syntax highlighting (although this is very limited within GitHub). The following is an example of an HTML code fragment:
FILENAME.ext |
|---|
<section class="section-std" id="js--020102a"> <!-- Start of section -->
<div class="rg-row sub-title-row"> <!-- Start of subtitle row -->
<div class="rg-col rg-span1-5"></div> <!-- Left column (not used) -->
<div class="rg-col rg-span3-5"> <!-- Start of subtitle column -->
<div class="sub-title-text-box">
<h4>Backwashing</h4></div>
</div> <!-- End of subtitle column -->
<div class="rg-col rg-span1-5"></div> <!-- Right column (not used) -->
</div> <!-- End of Subtitle row -->
<div class="rg-row"> <!-- Start of section content -->
<div class="rg-col rg-span1-5"> <!-- Start of left column -->
<!-- <aside class="aside-left"> Start of left side bar -->
<!-- <p></p> Side bar content -->
<!-- </aside> End of left side bar -->
</div> <!-- End of left column -->
</div> <!-- End of section content -->
</section> <!-- End of section --> |
| Code 16.1 — PS code fragment |
Like most other objects, the code fragment is placed in table, in this case with a header and a caption.
The header need not be included, it is generally used to hold a filename, but this is optional.
This is the code:
| Markdown |
|---|
|
|
<table name="c-16-10" align="center"><!-- CODE BLOCK START🔽🔽(BLANK LINE ABOVE) -->
<!-- Filename --><th align="right"><code>FILENAME.ext</code></th>
<tr><td><!-- START OF CODE BELOW (BLANK LINE BELOW) -->
```html
<section class="section-std" id="js--020102a"> <!-- Start of section -->
<div class="rg-row sub-title-row"> <!-- Start of subtitle row -->
<div class="rg-col rg-span1-5"></div> <!-- Left column (not used) -->
<div class="rg-col rg-span3-5"> <!-- Start of subtitle column -->
<div class="sub-title-text-box">
<h4>Backwashing</h4></div>
</div> <!-- End of subtitle column -->
<div class="rg-col rg-span1-5"></div> <!-- Right column (not used) -->
</div> <!-- End of Subtitle row -->
<div class="rg-row"> <!-- Start of section content -->
<div class="rg-col rg-span1-5"> <!-- Start of left column -->
<!-- <aside class="aside-left"> Start of left side bar -->
<!-- <p></p> Side bar content -->
<!-- </aside> End of left side bar -->
</div> <!-- End of left column -->
</div> <!-- End of section content -->
</section> <!-- End of section -->
```
</td></tr><!-- END OF CODE (BLANK LINE ABOVE) -->
<!-- CAPTION --> <tr>
<th align="center" width="200"><sup>
<!-- CAPTION TEXT -->Code 16.1 — PS code fragment
</sup></th></tr>
</table> <!-- CODE BLOCK END 🔼🔼(BLANK LINE BELOW) -->
|
| Table 16.33 — PS code fragment |
All PracticalSeries code fragments have a name attribute (just like everything else covered here) In this case it is in the form: c-cc-nn, where cc is the chapter number containing the list and nn is the consecutive numbering of the code fragment within the chapter, in this case it is c-16-01 meaning it is the first code fragment in chapter 16.
The code fragment is within a one column, 3 row table. The first row contains any associated filename, this is right aligned and displayed in a non-proportional font (hence the <code> tag).
The second row contains the code fragment itself, this starts with three backticks followed by the lowercase abbreviation for the language type (a full list of these is given in section 13.3.1), in this case it is ```html, for HTML code fragments.
The fragment terminates with three backticks. The starting and terminating backticks must be on their own line and have a blank line both above and below (as shown).
The third row of the table contains the code fragment caption. This works in the same way as those for images, tables and lists.
The width of the table must be specified (in this case it is a minimum width, the code fragment itself will determine the actual width of the table) The width of the table is set in the <th> tag of the caption with the width="200" attribute. In this case the table is set to a minimum width of 200 pixels.
Formulae (equations) can be displayed in two formats:
Firstly:
|
|
| Equation 16.1 — General quadratic equation |
|---|
Secondly (the alternative arrangement):
|
|
(16.2) |
|---|---|
| General quadratic equation | |
The first form of the formula is the standard arrangement, a one-column, 2 row table with the equation in the top row and a caption in the second row (very similar to the code fragment of the previous section).
The second form of the formula is an alternative form that can be used for multiple rows of equation with each row having its own equation number.
Taking each in turn:
|
|
| Equation 16.1 — General quadratic equation |
|---|
The Markdown is
| Markdown and GitHub output |
|---|
|
|
<table name="e-16-01" align="center"><!-- FORMULAE START🔽🔽(BLANK LINE ABOVE) -->
<tr><td><!-- START OF FORMULAE BELOW (BLANK LINE BELOW) -->
```math
x=\frac{-b\pm\sqrt{b^2—4ad}}{2a}
```
</td></tr><!-- END OF FORMULAE (BLANK LINE ABOVE) -->
<!-- CAPTION --> <tr>
<th align="center" width="400"><sup>
<!-- CAPTION TEXT --> Equation 16.1 — General quadratic equation
</sup></th></tr>
</table> <!-- FORMULAE END 🔼🔼(BLANK LINE BELOW) -->
|
| Table 16.34 — PS Standard formulae code |
Yes, it has a name attribute, just like everything else.
The formula is within a one column, 2 row table. The first row contains the formula itself, this is starts with three backticks followed by the lowercase math designation ```math, which will cause the equation to be rendered by GitHub. The equation terminates with three backticks.
The starting and terminating backticks must be on their own line and have a blank line both above and below (as shown).
The second row of the table contains the code fragment caption (a number followed by descriptive text) and is identical to those of tables, images and code fragments
The width of the table must be specified (in this case it is a minimum width, the formula itself will determine the actual width of the table) The width of the table is set in the <th> tag of the caption with the width="400" attribute. In this case the table is set to a minimum width of 400 pixels.
|
|
(16.2) |
|---|---|
| General quadratic equation | |
The Markdown is
| Markdown and GitHub output |
|---|
|
|
<table name="e-16-02" align="center"><!-- FORMULAE START🔽🔽(BLANK LINE ABOVE) -->
<tr><td><!-- START OF CODE BELOW (BLANK LINE BELOW) -->
```math
x=\frac{-b\pm\sqrt{b^2—4ad}}{2a}
```
</td><th width="60"><sup>(16.2)</sup></th></tr><!-- EQUATION NUMBER -->
</td></tr><!-- END OF CODE (BLANK LINE ABOVE) -->
<!-- CAPTION --> <tr>
<th align="center" width="400" colspan="2"><sup>
<!-- CAPTION TEXT --> General quadratic equation
</sup></th></tr>
</table> <!-- FORMULAE END 🔼🔼(BLANK LINE BELOW) -->
|
| Table 16.35 — PS alternate formulae code |
This format allows for multiple formulae rows to be added, each can have its own equation number in brackets in the right-hand column (16.2) in this case
The width of the equation number cell is fixed at 60 pixels. The overall (minimum) width of the table is set in the caption row width="400". This caption row spans both columns.
Multiple rows look like this:
|
|
(16.3) |
|---|---|
|
|
(16.4) |
| General quadratic equation | |
The Markdown is
| Markdown and GitHub output |
|---|
|
|
<table align="center"><!-- FORMULAE START🔽🔽(BLANK LINE ABOVE) -->
<tr name="e-16-03"><td><!-- START OF CODE BELOW (BLANK LINE BELOW) -->
```math
x=\frac{-b\pm\sqrt{b^2—4ad}}{2a}
```
</td><th width="60"><sup>(16.3)</sup></th></tr><!-- EQUATION NUMBER -->
</td></tr><!-- END OF CODE -->
<tr name="e-16-03"><td><!-- START OF CODE BELOW (BLANK LINE BELOW) -->
```math
derived \space from \space ax^2+bx+c=0
```
</td><th width="60"><sup>(16.4)</sup></th></tr><!-- EQUATION NUMBER -->
</td></tr><!-- END OF CODE -->
<!-- CAPTION --> <tr>
<th align="center" width="400" colspan="2"><sup>
<!-- CAPTION TEXT --> General quadratic equation
</sup></th></tr>
</table> <!-- FORMULAE END 🔼🔼(BLANK LINE BELOW) -->
|
| Table 16.36 — PS alternate formulae, multiple rows |
The PracticalSeries sidebar is primarily a navigation bar and a table of contents (TOC) for the Wiki. It looks like this:
|
| Figure 16.17 — PracticalSeries sidebar format |
|---|
It is made up of five parts:
| ❶ | Title bar and storage location badge |
| ❷ | Navigation bar |
| ❸ | Main table of contents |
| ❹ | Table of contents for the appendices |
| ❺ | A link to the bottom of the page (end of page link) |
| List 16.17 — Sidebar components |
|---|
Each of these is examined in turn in the following sections.
The PracticalSeries Wiki pages all have a unique sidebar page (the exceptions being the CaseNotes and Licence pages which share a sidebar page).
Every sidebar has its own Markdown file called: _sidebar.md
The only thing that differentiates one sidebar from another is the location (folder) where it is stored. This was explained full in section 4, but a brief recap is given below.
The PracticalSeries folder structure has a separate folder of each page in the Wiki, the folder and page name for this section being:
16-0000/16 PracticalSeries Wiki conventions.md
It is in the folder 16-0000; if a file called _sidebar.md is present in the same folder, then GitHub will display that _sidebar.md file as the sidebar for any Wiki page in that folder (in this case: 16 PracticalSeries Wiki conventions.md).
If there is no _sidebar.md file in the folder, it will display the _sidebar.md file that is in the root folder (where the Home.md page is)
So that’s it, every page in the Wiki lives in its own folder (see section 3 and section 16.2 for full details) and each of these folders has an _sidebar.md file that is the sidebar for that particular page.
This is the first entry for every _sidebar.md file. The title is always the same for every sidebar:
Also on this line is a badge that has the folder name that contains the _sidebar.md file:
|
| Figure 16.18 — Sidebar title and badge |
|---|
Note
The pencil icon is created by GitHub and allows me to edit the sidebar
| Markdown |
|---|
|
|
### Wiki contents<img width="107" height="1" src="https://psop.uk/wi-s" alt="Spacer"><!-- LOCATION BADGE --><img height="15px" src="https://img.shields.io/badge/loc-06--0700-808080">
|
| Table 16.37 — Sidebar title and location badge |
It is a standard Markdown level 3 title (3 hashes, see section 6.10) with the text: Wiki contents.
This is followed by spacing image (107 pixels wide by 1 pixel high), see section 11.4. this creates the gap between the title text and pushes the badge to the right-hand side of the sidebar.
The badge is a Shields.IO badge, it has the label loc followed by the folder name where the sidebar.md file is located, in this case it is the folder 06-0700, this is written in the badge URL as 06--0700, the double dash being an escape code to display a single dash, see section 15.2. The number 808080 is the light grey background colour for the badge
The navigation bar has the following appearance:
|
| Figure 16.19 — Navigation bar icons and meaning |
|---|
This navigation bar is exactly the same as that discussed in section 15.1 and I refer you there for the details of its construction.
The table of contents is the same for every sidebar (they all have a full table of contents for every page in the Wiki). The only difference being that the TOC associated with the chapter of the current page is shown opened, this is the sidebar TOC for chapter 1:
|
| Figure 16.20 — Sidebar TOC |
|---|
The chapter 1 TOC is open (collapsible arrow pointing down), all other chapter TOCs are closed (collapsible arrow pointing right).
Obviously, the TOCs are different for different Wikis, however, the general appearance of the TOC is consistent, the heading text all lines up for example.
Each line of the TOC has indentation to separate the chapter/section/division numbers from the text, it can be seen here:
|
| Figure 16.21 — TOC indentation |
|---|
The indentations are designed to allow the widest number: cc.ss.dd, all with double digits to fit in the gap before the section and division headings. Chapter headings are less indented. The whole thing has a symmetrical and pleasing appearance.
The following Markdown examples cover all the various types of TOC:
| ❶ |
Unnumbered heading without collapsible content (like Home and CaseNotes in the above image) |
| ❷ |
Unnumbered, collapsible TOC (like Licence in the above image) |
| ❸ | Single digit chapter, collapsible (like chapter 1 in the above image) |
| ❹ | Double digit chapter, collapsible (as above but with at two-digit chapter number) |
| List 16.18 — Types of TOC |
|---|
Taking each in turn:
In all these examples the following definitions are applied
| Item | Definition |
|---|---|
|
|
The Wiki page name in link format (section&9.2.1) |
|
|
The Wiki heading name in link format (section 9.3.1) |
|
|
The heading number (displayed text) |
|
|
The heading text in plain English (displayed text) |
|
|
Comment field, should contain the section name or number |
| Table 16.38 — TOC common elements | |
|
| Figure 16.22 — Unnumbered, non-collapsible TOC |
|---|
The Markdown is:
| Markdown |
|---|
|
|
<!-- [SECTION_NAME] 🟢🟢🟢 UNNUMBERED, NO COLLAPSE -->
     <a href="./page"><!-- HEAD -->Heading_Unnumbered_noCollapse</a>
<!-- 🟩🟩🟩 -->
|
| Table 16.39 — TOC entry: unnumbered, non-collapsible |
The following is a worked example for the home page:
| Markdown |
|---|
|
|
<!-- [CASENOTES] 🟢🟢🟢 UNNUMBERED, NO COLLAPSE -->
     <a href="casenotes"><!-- HEAD -->CaseNotes</a>
<!-- 🟩🟩🟩 -->
|
| Table 16.40 — TOC entry: unnumbered, non-collapsible example |
|
| Figure 16.23 — Unnumbered, collapsible TOC |
|---|
The Markdown is:
| Markdown |
|---|
|
|
<details><!-- [SECTION_NAME] 🟢🟢🟢 UNNUMBERED, COLLAPSIBLE -->
<summary>   <a href="./page"><!-- HEAD -->Heading_Unnumbered_Collapsible</a>
</summary><!-- BLANK LINE BELOW -->
       [Heading](page#heading)<br>
       [Heading](page#heading)<br>
       [Heading](page#heading)<br>
       [Heading](page#heading)<br>
       [Heading](page#heading)<br>
</details><!-- 🟩🟩🟩 -->
|
| Table 16.41 — TOC entry: unnumbered, collapsible |
The following is a worked example for the Licence page:
| Markdown |
|---|
|
|
<details ><!-- LICENCE 🟢🟢🟢 UNNUMBERED, COLLAPSIBLE -->
<summary>   <a href="licence"><!-- HEAD -->Licence</a>
</summary><!-- BLANK LINE BELOW -->
       [The licences and other details](licence#the-licences-and-other-details)<br>
       [The Licence](licence#the-licence)<br>
       [Why did I choose the MIT Licence?](licence#why-did-i-choose-the-mit-licence)<br>
       [Permissive licences](licence#permissive-licences)<br>
       [Copyleft licence](licence#copyleft-licence)<br>
       [Limiting liabilities](licence#limiting-liabilities)<br>
       [Which licence to use?](licence#which-licence-to-use)<br>
       [A note on spelling: licence or license](licence#a-note-on-spelling-licence-or-license)<br>
</details><!-- 🟩🟩🟩 -->
|
| Table 16.42 — TOC entry: unnumbered, collapsible example |
To make the list default to open replace <details> with <details open>.
|
| Figure 16.24 — Single digit chapter, collapsible TOC |
|---|
The Markdown is:
| Markdown |
|---|
|
|
<details><!-- [SECTION_NAME] 🟢🟢🟢 SECTION GENERAL SINGLE DIGIT CHAPTER-->
<summary><a href="./page">0<!-- NUM -->   <!-- HEAD -->Heading_Chap_1_Digit</a>
</summary><!-- BLANK LINE BELOW -->
   [0.0     HeadingSec](page#heading)<br>
   [0.00    HeadingSec](page#heading)<br>
   [0.0.0  HeadingDiv](page#heading)<br>
   [0.00.0  HeadingDiv](page#heading)<br>
   [0.00.00  HeadingDiv](page#heading)<br>
       [HeadingInln](page#heading)<br>
</details><!-- 🟩🟩🟩 -->
|
| Table 16.43 — TOC entry: single digit chapter, collapsible |
This has the following appearance:
|
| Figure 16.25 — Single digit chapter, collapsible TOC pro-forma |
|---|
The following is a worked example for the 02 Cloning a Wiki page:
| Markdown |
|---|
|
|
<details><!-- [SECTION 02] 🟢🟢🟢 SECTION GENERAL SINGLE DIGIT CHAPTER-->
<summary><a href="./02-cloning-a-wiki">2<!-- NUM -->   <!-- HEAD -->Cloning a Wiki</a>
</summary><!-- BLANK LINE BELOW -->
   [2.1     Why clone a Wiki?](02-cloning-a-wiki#21why-clone-a-wiki)<br>
   [2.2     How to clone a Wiki](02-cloning-a-wiki#22how-to-clone-a-wiki)<br>
   [2.3     Pushing local changes to GitHub](02-cloning-a-wiki#23pushing-local-changes-to-github)<br>
   [2.3.1  Configuring username and email](02-cloning-a-wiki#231configuring-a-git-username-and-email-address)<br>
   [2.3.2  Modifying the local repository](02-cloning-a-wiki#232modifying-the-local-repository)<br>
   [2.3.3  Committing and synchronising](02-cloning-a-wiki#233committing-and-synchronising-the-changes)<br>
</details><!-- 🟩🟩🟩 -->
|
| Table 16.44 — TOC entry: single digit chapter, collapsible example |
To make the list default to open replace <details> with <details open>.
|
| Figure 16.26 — Double digit chapter, collapsible TOC |
|---|
The Markdown is:
| Markdown |
|---|
|
|
<details><!-- [SECTION_NAME] 🟢🟢🟢 SECTION GENERAL DOUBLE DIGIT CHAPTER-->
<summary><a href="./page">00<!-- NUM -->  <!-- HEAD -->Heading_Chap_2_Digit</a>
</summary><!-- BLANK LINE BELOW -->
   [00.0    HeadingSec](page#heading)<br>
   [00.00   HeadingSec](page#heading)<br>
   [00.0.0   HeadingSecHeadingDiv](page#heading)<br>
   [00.00.0  HeadingDiv](page#heading)<br>
   [00.00.00 Heading](page#heading)<br>
       [HeadingInln](page#heading)<br>
</details><!-- 🟩🟩🟩 -->
|
| Table 16.45 — TOC entry: double digit chapter, collapsible |
This has the following appearance:
|
| Figure 16.27 — Double digit chapter, collapsible TOC pro-forma |
|---|
The following is a worked example for the 15 Navigation bars, badges and buttons page:
| Markdown |
|---|
|
|
<details><!-- [SECTION 15] 🟢🟢🟢 SECTION GENERAL DOUBLE DIGIT CHAPTER-->
<summary><a href="./15-navigation-bars,-badges-and-buttons">15<!-- NUM -->  <!-- HEAD -->Navigation bars, badges and buttons</a>
</summary><!-- BLANK LINE BELOW -->
   [15.1    Navigation bars](15-navigation-bars,-badges-and-buttons#151navigation-bars)<br>
   [15.1.1   Navigation bar practicalities](15-navigation-bars,-badges-and-buttons#1511navigation-bar-practicalities)<br>
   [15.2    Badges](15-navigation-bars,-badges-and-buttons#152badges)<br>
   [15.2.1   Creating a badge](15-navigation-bars,-badges-and-buttons#1521creating-a-badge)<br>
   [15.2.2   Static badge options](15-navigation-bars,-badges-and-buttons#1522static-badge-options)<br>
   [15.2.3   Dynamic badges](15-navigation-bars,-badges-and-buttons#1523dynamic-badges)<br>
   [15.3    Buttons](15-navigation-bars,-badges-and-buttons#153buttons)<br>
</details><!-- 🟩🟩🟩 -->
|
| Table 16.46 — TOC entry: double digit chapter, collapsible example |
To make the list default to open replace <details> with <details open>.
TOCs for appendices are contained within an additional collapsible block:
|
| Figure 16.28 — Collapsed appendices TOC |
|---|
When expanded, the TOC looks like this:
|
| Figure 16.29 — Expanded appendices TOC |
|---|
The appendices TOC is separated from the main TOC with a horizontal bar, the code for this and the top-level collapsible block is:
The Markdown is:
| Markdown |
|---|
|
|
<!-- APPENDICES -->
<hr><!-- SEPARATOR -->
<details><!-- APPENDICES TOP 🔴🔴🔴 LEVEL COLLAPSE -->
<summary><a href="./page"><!-- APP TOP LEVEL -->Appendices</a>
</summary>
<br><!-- BLANK LINE BELOW -->
<!--INDIVIDUAL TOCs FOR EACH APPENDIX GO HERE -->
</details><!-- APPENDICES TOP🟥🟥🟥 LEVEL COLLAPSE -->
|
| Table 16.46 — Top level Appendices TOC collapsible block |
Individual TOCs for each appendix go in the orange area, these are very similar to the Single digit chapter, collapsible TOCs.
The only differences are to do with the spacings. Appendices use a capital letter in place of a chapter number and whereas the numbers (at the reduced size of the sidebar text) are all approximately the same width, the capital letters vary considerably.
There are some commonalities, the following letters are grouped in matching widths:
| ● | A, C, V, R |
| ● | B, K, P, S, T, X, Y, Z |
| ● | D, G, H, N, O, Q, U |
| ● | E, F, L |
| ● | I |
| ● | J |
| ● | M |
| ● | W |
| List 16.19 — Letter groups |
|---|
There are separate TOC groups for each of these.#
The code for each group is as follows:
| Markdown |
|---|
|
|
<details><!-- [APP_NAME] 🟡🟡🟡 SECTION GENERAL SINGLE DIGIT CHAPTER-->
<summary><a href="./page">A<!-- NUM -->   <!-- HEAD -->Heading_App_Digit_A_C_R_V</a>
</summary><!-- BLANK LINE BELOW -->
   [A.0    HeadingSec](page#heading)<br>
   [A.00   HeadingSec](page#heading)<br>
   [A.0.0   HeadingDiv](page#heading)<br>
   [A.00.0   HeadingDiv](page#heading)<br>
   [A.00.00   HeadingDiv](page#heading)<br>
       [HeadingInln](page#heading)<br>
</details><!-- 🟨🟨🟨 -->
|
|
|
<details><!-- [APP_NAME] 🟡🟡🟡 SECTION GENERAL SINGLE DIGIT CHAPTER-->
<summary><a href="./page">B<!-- NUM -->   <!-- HEAD -->Heading_App_Digit_B_K_P_S_T_X_Y_Z</a>
</summary><!-- BLANK LINE BELOW -->
   [B.0     HeadingSec](page#heading)<br>
   [B.00    HeadingSec](page#heading)<br>
   [B.0.0  HeadingDiv](page#heading)<br>
   [B.00.0  HeadingDiv](page#heading)<br>
   [B.00.00  HeadingDiv](page#heading)<br>
       [HeadingInln](page#heading)<br>
</details><!-- 🟨🟨🟨 -->
|
|
|
<details><!-- [APP_NAME] 🟡🟡🟡 SECTION GENERAL SINGLE DIGIT CHAPTER-->
<summary><a href="./page">D<!-- NUM -->  <!-- HEAD -->Heading_App_Digit_D_G_H_N_O_Q_U</a>
</summary><!-- BLANK LINE BELOW -->
   [D.0    HeadingSec](page#heading)<br>
   [D.00   HeadingSec](page#heading)<br>
   [D.0.0   HeadingDiv](page#heading)<br>
   [D.00.0   HeadingDiv](page#heading)<br>
   [D.00.00   HeadingDiv](page#heading)<br>
       [HeadingInln](page#heading)<br>
</details><!-- 🟨🟨🟨 -->
|
|
|
<details><!-- [APP_NAME] 🟡🟡🟡 SECTION GENERAL SINGLE DIGIT CHAPTER-->
<summary><a href="./page">E<!-- NUM -->  <!-- HEAD -->Heading_App_Digit_E_F_L</a>
</summary><!-- BLANK LINE BELOW -->
   [E.0     HeadingSec](page#heading)<br>
   [E.00    HeadingSec](page#heading)<br>
   [E.0.0   HeadingDiv](page#heading)<br>
   [E.00.0    HeadingDiv](page#heading)<br>
   [E.00.00  HeadingDiv](page#heading)<br>
       [HeadingInln](page#heading)<br>
</details><!-- 🟨🟨🟨 -->
|
|
|
<details><!-- [APP_NAME] 🟡🟡🟡 SECTION GENERAL SINGLE DIGIT CHAPTER-->
<summary><a href="./page">I<!-- NUM -->    <!-- HEAD -->Heading_App_Digit_I</a>
</summary><!-- BLANK LINE BELOW -->
   [I.0    HeadingSec](page#heading)<br>
   [I.00     HeadingSec](page#heading)<br>
   [I.0.0    HeadingDiv](page#heading)<br>
   [I.00.0    HeadingDiv](page#heading)<br>
   [I.00.00   HeadingDiv](page#heading)<br>
       [HeadingInln](page#heading)<br>
</details><!-- 🟨🟨🟨 -->
|
|
|
<details><!-- [APP_NAME] 🟡🟡🟡 SECTION GENERAL SINGLE DIGIT CHAPTER-->
<summary><a href="./page">J<!-- NUM -->    <!-- HEAD -->Heading_App_Digit_I</a>
</summary><!-- BLANK LINE BELOW -->
   [J.0     HeadingSec](page#heading)<br>
   [J.00     HeadingSec](page#heading)<br>
   [J.0.0    HeadingDiv](page#heading)<br>
   [J.00.0    HeadingDiv](page#heading)<br>
   [J.00.00   HeadingDiv](page#heading)<br>
       [HeadingInln](page#heading)<br>
</details><!-- 🟨🟨🟨 -->
|
|
|
<details><!-- [[APP_NAME] 🟡🟡🟡 SECTION GENERAL SINGLE DIGIT CHAPTER-->
<summary><a href="./page">M<!-- NUM -->   <!-- HEAD -->Heading_App_Digit_M</a>
</summary><!-- BLANK LINE BELOW -->
   [M.0   HeadingSec](page#heading)<br>
   [M.00  HeadingSec](page#heading)<br>
   [M.0.0   HeadingDiv](page#heading)<br>
   [M.00.0  HeadingDiv](page#heading)<br>
   [M.00.00  HeadingDiv](page#heading)<br>
       [HeadingInln](page#heading)<br>
</details><!-- 🟨🟨🟨 -->
|
|
|
<details><!-- [APP_NAME] 🟡🟡🟡 SECTION GENERAL SINGLE DIGIT CHAPTER-->
<summary><a href="./page">W<!-- NUM -->   <!-- HEAD -->Heading_App_Digit_W</a>
</summary><!-- BLANK LINE BELOW -->
   [W.0   HeadingSec](page#heading)<br>
   [W.00    HeadingSec](page#heading)<br>
   [W.0.0   HeadingDiv](page#heading)<br>
   [W.00.0  HeadingDiv](page#heading)<br>
   [W.00.00  HeadingDiv](page#heading)<br>
       [HeadingInln](page#heading)<br>
</details><!-- 🟨🟨🟨 -->
|
| Table 16.47 — Individual TOC for all 26 Appendix letters |
The end of page link is identical on every sidebar:
|
| Figure 16.30 — End of page link |
|---|
This is simply the end of page link discussed in section 9.5, wrapped in a table.
The code is:
| Markdown |
|---|
|
|
<table align="center"><tr><!-- 🟣END OF PAG🟣E -->
<td><a href="#idend"><strong>⬇️ End of page</strong></a></td>
</tr></table>
|
| Table 16.48 — End of page link |
It requires the end of page anchor point to be the last thing on the associated Wiki page, see section 16.5.1.
The PracticalSeries footer is primarily a navigation bar (identical to that isn the sidebar), a colophon and a list of contacts and web links. It looks like this:
|
| Figure 16.31 — PracticalSeries footer format |
|---|
| ● | MainPoint |
| ● | MainPoint |
| ● | MainPoint |
| ● | MainPoint |
| ● | MainPoint |
| ● | MainPoint |
| ● | MainPoint |
| ● | MainPoint |
| ● | MainPoint |
| ● | MainPoint |
| List 16.20 — Footer components |
|---|
- 16PracticalSeries Wiki conventions
-
AHeading_level_1
- A.1Heading_level_2
-
B.20Heading_level_2
- A.1.1Heading_level_3
- B.1.10Heading_level_3
- C.11.4Heading_level_3
- 16.5.3Tables
- 16.5.4Images
-
16.5.5Lists
- Common points for all lists
- PS basic unordered list
- PS basic ordered list
- PS mixed ordered and unordered lists
- PS enhanced mixed ordered and unordered lists
- PS index list
- PS reverse index list
- PS index list with text wrap
- PS reverse index list with text wrap
- PS indexed, mixed list
- PS reverse indexed, mixed list
- PS task list
- PS enhanced task list with observations
- 16.5.6Code fragments
- 16.5.7Formulae
- 16.6Sidebar
- 16.7Footer
|
|
|
|
|
|
The PracticalSeries of Publications — Copyright © 2025 Michael Gledhill
⬆️ Top | mg@practicalseries.com | PracticalSeries of Publications | Main repository
|
|
|
|
|
|
Licence
The licences and other details
The Licence
Why did I choose the MIT Licence?
Permissive licences
Copyleft licence
Limiting liabilities
Which licence to use?
A note on spelling: licence or license
1 Introducing the GitHub Wiki
1.1 What are GitHub Wiki pages?
1.2 Understanding the Wiki pages
1.3 Creating a Wiki for a repository
1.3.1 Creating the first Wiki page
1.3.2 Creating additional pages
1.3.3 Editing a Wiki page
1.4 The Wiki is its own repository
1.4.1 Viewing a Wiki page history
1.4.2 How GitHub handles Wiki branche
1.4.3 The Wiki link to the main repository
1.5 Basic components of a Wiki page
1.5.1 Title bar and revision
1.5.2 Contents (pages) area
Listing pages in the order you want
1.5.3 Sidebars
1.5.4 Footers
1.6 Sidebars and footers
1.6.1 Creating a sidebar and footer
2 Cloning a Wiki
2.1 Why clone a Wiki?
2.2 How to clone a Wiki
2.3 Pushing local changes to GitHub
2.3.1 Configuring username and email
2.3.2 Modifying the local repository
2.3.3 Committing and synchronising
3 A Wiki folder structure
3.1 The default arrangement
3.2 Create a sidebar or footer locally
3.3 Page naming and Wiki limits
3.3.1 Supported file types
3.3.2 Page names and numbering
3.3.3 Rules for page numbering
3.3.4 Limits for Wiki pages
3.4 A Practical Wiki folder structure
3.4.1 Subfolder names for Wiki pages
3.4.2 Storing images and other data
4 Different sidebars and footers
4.1 How sidebars work
4.1.1 The PracticalSeries sidebar
4.2 How footers work
4.2.1 The PracticalSeries footer
5 Markdown, GitHub Markdown and HTML
5.1 Some useful Markdown sites
5.2 An overview of Markdown
5.3 How Markdown works
5.4 Markdown flavours
5.4.1 GitHub Flavoured Markdown (GFM)
5.5 HTML and Markdown
5.5.1 HTML with GFM
GFM blacklisted HTML tags
GFM whitelisted HTML tags
GFM HTML tags - the grey area
GFM whitelisted HTML attributes
5.5.2 PracticalSeries and Markdown
5.6 Markdown difference between files
6 Basic Markdown and text formatting
6.1 Body text and fonts
6.1.1 Body text responsive design
6.1.2 Body text in sidebars and footers
6.1.3 Rules for body text
6.1.4 Body text examples
6.1.5 Alignment of Body text
Left aligned text (default)
Right aligned text
Centred text
Justified text
6.1.6 Body text propertie
6.2 Paragraphs and line breaks
6.2.1 Forced line break
6.2.2 Blank line and a line break
6.2.3 Trailing space line break
6.2.4 Paragraph and line break rules
6.2.5 Paragraph and line break examples
6.3 Horizontal line
6.3.1 Rules for horizontal lines
6.4 Emphasis with bold
6.4.1 Rules for bold
6.4.2 Bold text examples
6.5 Emphasis with italics
6.5.1 Rules for italics
6.5.2 Italic text examples
6.6 Emphasis with bold and italics
6.6.1 Rules for bold and italics
6.6.2 Bold and italic text examples
6.7 Emphasis with underlining
6.7.1 Rules for underlining
6.7.2 Underlining text examples
6.8 Emphasis with strikethrough
6.8.1 Rules for strikethrough
6.8.2 Strikethrough text examples
6.9 Superscript and subscript
6.9.1 Rules for superscript and subscript
6.9.2 Superscript and subscript examples
6.10 Headings
Alternatives for heading 1 and 2
6.10.1 Headings Markdown rules
6.10.2 Heading properties
7 Special characters and escaping characters
7.1 Escape characters and codes
7.1.1 Markdown escape sequences
7.1.2 HTML escape sequences
7.1.3 Decimal and hexadecimal codes
Hexadecimal escape codes
7.2 Special space characters
7.2.1 Escape sequence restrictions
7.3 Emojis and emoticons
A note by the Author about emojis
7.4 Comments
8 Block quotes, lists and alerts
8.1 Block quotes
8.1.1 Nested block quotes
8.1.2 Adding other elements
8.1.3 Rules for block quotes
8.2 Unordered (unnumbered) lists
8.2.1 Nested unordered lists
8.2.2 Type of bullet point
8.2.3 Indents and spacing
8.2.4 Numbers in an unordered list
8.2.5 Adding paragraphs
8.2.6 Adding other elements
8.2.7 Rules for unordered lists
8.3 Ordered (numbered) lists
8.3.1 Starting at a different number
8.3.2 Nested ordered lists
8.3.3 Type of numbering
8.3.4 Indents and spacing
8.3.5 Adding paragraphs
8.3.6 Adding other elements
8.3.7 Rules for ordered lists
8.4 Mixing ordered and unordered lists
8.5 Task lists (check boxes)
8.5.1 Nested task lists
8.6 Alerts
8.6.1 Rules for alerts
9 Links
9.1 Link to an external web page
9.1.1 A direct link to a URL
9.1.2 A link using substitute text
9.1.3 A link using tooltips
9.2 Link to another page in the Wiki
9.2.1 Rules for linking to a Wiki page
9.3 Link to headings on current page
9.3.1 Converting a heading to a link
9.3.2 An example of a heading link
9.3.3 Heading link with tooltips
9.4 Link to headings on a different page
9.4.1 An example of a heading link
9.5 Link to a named element
A note by the Author
9.5.1 Link to a point on another page
9.6 Downloading a file
9.6.1 The download attribute
9.6.2 Spaces in filenames
9.6.3 Downloading a .md file
9.7 Reference style links
9.8 Relative links
9.8.1 Relative links from any Wiki page
10 Tables
10.1 Markdown tables
10.1.1 Horizontal alignment
10.1.2 Table construction
10.1.3 Vertical line breaks and alignment
10.1.4 Making columns wider
10.1.5 Other elements in a table
10.1.6 Markdown table restrictions
10.2 HTML tables
10.2.1 A basic HTML table
10.2.2 Aligning a table on a page
10.2.3 Text wrap and side-by-side tables
What this means in practice
The problem with the align attribute
How to stop text wrapping
10.2.4 Setting the width of a table column
10.2.5 Setting the height of a table row
10.2.6 Horizontal alignment
10.2.7 Vertical alignment
10.2.8 Spanning columns and rows
10.2.9 Table border
10.2.10 Giving a table a navigable name
10.2.11 Additional HTML tags
11 Images
11.1 Markdown images
11.1.1 Image size in Markdown
11.1.2 Making the image a link
11.1.3 Drag and drop image link
A note by the Author
11.2 HTML images
11.2.1 A basic HTML image
11.2.2 Image size in HTML
11.2.3 Horizontal alignment
11.2.4 Making the image a link
11.2.5 Using a table to contain an image
11.3 Forcing an image refresh
11.4 Using a spacer image
11.5 Mermaid diagrams
11.5.1 Inserting a Mermaid diagram
11.5.2 The rendered Mermaid diagram
11.5.3 Supported version of Mermaid
11.6 Interactive maps
11.7 3D models
12 Contents (collapsible) and footnotes
12.1 A basic table of contents
12.2 Understanding the space characters
12.3 Collapsible content
12.3.1 Defaulting to open
12.3.2 Markdown restrictions
12.4 Collapsible TOC
12.5 TOCs in tables
12.6 Footnotes
13 Code fragments
13.1 Inline code
13.2 Code blocks
13.2.1 Preferred mechanism
13.3 Syntax highlighting
13.3.1 Supported languages
13.4 HTML code fragments
13.4.1 Converting HTML to code
14 Mathematical formulae
14.1 An overview of LaTex
14.2 Inserting an inline formula
14.2.1 Alternative delimiter
14.3 A formula block
14.4 Some example formulae
14.5 LaTeX syntax
14.5.1 Greek lowercase
14.5.2 Greek uppercase and Hebrew
14.5.3 Mathematical constructions
14.5.4 Variable sized delimiters
14.5.5 Variable sized symbols
14.5.6 Variable sized symbols with limits
14.5.7 Standard functions
14.5.8 Operators and relational symbols
14.5.9 Arrows
14.5.10 Other symbols
14.5.11 Accents
14.5.12 Matrices
14.5.13 Cases
Aligning multiple equations
14.5.14 Text formatting
Font size
Font colour
The text command
Font restrictions
14.6 Abusing LaTeX
14.6.1 Changing font colour with LaTeX
15 Navigation bars, badges and buttons
15.1 Navigation bars
15.1.1 Navigation bar practicalities
15.2 Badges
15.2.1 Creating a badge
15.2.2 Static badge options
15.2.3 Dynamic badges
15.3 Buttons
16 PracticalSeries Wiki conventions
16.1 The PracticalSeries Wiki page
16.2 The PracticalSeries folder structure
16.2.1 The root folder and home page
16.2.2 Leading pages
16.2.3 .gitkeep files
16.2.4 Folder and Markdown file names
Wiki pages that start at a section
16.3 The page title area
16.4 The page heading area
16.4.1 Top of page marker
16.4.2 Logo image
16.4.3 Web ID badge
16.5 Main body area
16.5.1 Common page elements
End of page marker
End of section elements
16.5.2 Headings
Compensating for number widths
Appendices headings
16.5.3 Tables
Links to a table
A note on Markdown tables
16.5.4 Images
Images that open in a new tab
Double images
Links to a figure
16.5.5 Lists
Common points for all lists
Basic unordered list
Basic ordered list
Mixed ordered and unordered lists
Enhanced mixed lists
Index list
Reverse index list
Index list with text wrap
Reverse index list with text wrap
Indexed, mixed list
Reverse indexed, mixed list
Task list
Enhanced task list with observations
16.5.6 Code fragments
16.5.7 Formulae
Standard formulae
Alternate formulae
16.6 Sidebar
16.6.1 sidebar files and locations
16.6.2 Sidebar title and location badge
16.6.3 Navigation bar
16.6.4 Table of contents
Unnumbered, non-collapsible TOC
Unnumbered, collapsible TOC
Single digit, collapsible TOC
Double digit, collapsible TOC
TOCs for appendices
16.6.5 End of page link
16.7 Footer
16.7.1 Footer files and locations
16.7.2 Location badge
16.7.3 Navigation bar
16.7.4 Colophon
16.7.5 Links and contacts
17 Managing a Wiki
17.1 Revision control
17.1.1 Managing commits
17.2 Finding the first Wiki commit
17.3 Rebasing the Wiki
17.3.1 Summarising the rebase process
17.3.2 Executing the rebase process
17.4 Wikis and search engine visibility
Appendices
B Full list of all emoji characters
B.1 Emojis, a brief explanation
B.1.1 Emoji short names
B.1.2 Emoji escape codes
B.1.3 Emoji variations
B.1.4 Emoji numbers
B.2 Emojis characters by category
Smileys and emotion
People and body
Component
Animals and nature
Food and drink
Travel and places
Activities
Objects
Symbols
Flags
B.3 Emoji characters by Unicode
C Segoe UI full character set
A note by the Author
C.1 Inserting Unicode characters
C.2 Characters U+00000 to U+00FFF
C.3 Characters U+01000 to U+01FFF
C.4 Characters U+02000 to U+02FFF
C.5 Characters U+03000 to U+09FFF
C.6 Characters U+0A000 to U+0AFFF
C.7 Characters U+0B000 to U+0FFFF
C.8 Characters U+10000 to U+10FFF
C.9 Characters U+11000 to U+11FFF
C.10 Characters U+12000 to U+12FFF
C.11 Characters U+13000 to U+15FFF
C.12 Characters U+16000 to U+1CFFF
C.13 Characters U+1D000 to U+1EFFF
C.14 Characters U+1F000 to U+3FFFF
| ⬇️ End of page |