16.06 PracticalSeries Wiki conventions - practicalseries/GitHub-Wiki-Design-and-Implementation GitHub Wiki
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 |
|---|
It is made up of four parts:
| β | Location badge |
| β | Navigation bar |
| β | Colophon |
| β | Links and contacts |
| List 16.20 β Footer components |
|---|
Each of these is examined in turn in the following sections.
Footer files for a particular page are called _footer.md. These work in exactly the same way as the _sidebar.md files discussed in section 16.6.1 and are stored in exactly the same folder as the associated sidebar. See section 16.6.1
The location badge (top-right of the footer) is identical to that of the associate sidebar. It has the following Markdown:
| Markdown |
|---|
|
|
<p align="right"><!-- LOCATION BADGE --><img height="15px" src="https://img.shields.io/badge/loc-cc--ssdd-808080">
|
| Table 16.49 β Footer location badge |
It is simply a right aligned version of the Shields.IO badge used in the sidebar (see section 16.6.2). Everything within the <img> tag can be copied from the associated sidebar and pasted into the footer.
The footer navigation bar is identical to that of the sidebar associated with the same page, it can be copied and pasted directly from that sidebar. See section 16.6.3 and section 15.1
The colophon contains the publisher and copyright information for the Wiki:
|
| Figure 16.32 β Footer colophon |
|---|
This is the code:
| Markdown |
|---|
|
|
<!--- COLOPHON -->
<p align="center"><strong><!-- NAME -->The PracticalSeries of Publications — <!-- COPYRGT -->Copyright © 2024 Michael Gledhill</strong></p>
|
| Table 16.50 β Footer colophon |
It is simply a centred text string containing the publisher and the copyright owner.
The markdown for this is:
| Markdown |
|---|
|
|
<!--- LINKS AND LOCATION BADGE -->
<p align="center">
<!-- TOP --><a href="#idtop">β¬οΈ Top</a>   |  
<!-- EMAIL --><a href="mailto:[email protected]">[email protected]</a>   |  
<!-- WEB --><a href="https://practicalseries.com/">PracticalSeries of Publications</a>   |  
<!-- REPO --><a href="https://github.com/practicalseries/GitHub-Wiki-Design-and-Implementation">Main repository</a></p>
|
| Table 16.51 β Footer colophon |
It is simply four links, the first, a standard link to the top of the page, the second is an email link, the third a link to the associated website and the fourth a link to the parent repository.
|
|
|
|
|
|
The PracticalSeries of Publications β Copyright Β© 2025 Michael Gledhill
β¬οΈ Top β | β [email protected] β | β PracticalSeries of Publications β | β Main repository