12 contents, collapsible content and footnotes - practicalseries/GitHub-Wiki-Design-and-Implementation GitHub Wiki
Tables of contents (TOCs) form an important part of a Wiki, PracticalSeries Wikis all have a table of contents in the sidebar, these are in a collapsible form that can be expanded or contracted by clicking a small black arrow at the side of the link.
Each entry in the TOC is a link that navigates to the appropriate section when clicked. This section explains how to construct a table of contents, how to make it collapsible and how to automatically produce the TOC entries.
Footnotes are also covered in this section. Footnotes are a peculiarity with GitHub Wikis; normally, footnotes can be created directly in the Markdown and using specific formatting characters that tell GitHub itβs a footnote and GitHub then creates a link to the footnote entry and from there, back to the original point in the body text. At least it does in normal Markdown files in a repository.
For some reason, footnotes donβt work in Wiki Markdown files. I have no reason why this should be. But there we go.
Iβve come up with a workaround to allow footnotes and their linkage to work on Wiki pages, and it is explained in this section.
A table of contents (TOC) is simply a list of the heading on a page (or on many Wiki pages) that form navigable links to the appropriate page and heading.
These links are identical to those discussed in section 9.3 and section 9.4. The following is an extract of the TOC from this Wiki (it appears in the sidebar of the following page: https://github.com/practicalseries/GitHub-Wiki-Design-and-Implementation/wiki/01-Introducing-the-GitHub-Wiki).
|
| Figure 12.1 β Table of contents in a sidebar |
|---|
The Markdown behind this is:
| Markdown and GitHub output |
|---|
|
|
     [Home](home)<br><!-- HOME -->
     [Casenotes](casenotes)<br><!-- CASENOTES -->
     [The licences and other details](licence)<br><!-- LICENCE -->
       [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#a-note-on-spelling-licence-or-license)<br>
  [1   Introducing the GitHub Wiki](01-Introducing-the-GitHub-Wiki)<br><!--SEC 01 -->
   [1.3     Creating a Wiki](01-Introducing-the-GitHub-Wiki#13creating-a-wiki-for-a-repository)<br>
|
|
|
|
βββββHome βββββCasenotes βββββThe licences and other details β 1β βIntroducing the GitHub Wiki |
| Table 12.1 β A basic table of contents in Markdown |
Note
The <br> at the end of each line is required (the lines join up otherwise).
Ignoring all the special space characters at the start (these are just used to pad the links to the correct indentation), it becomes:
| Markdown and GitHub output |
|---|
|
|
[Home](home)<br>
[Casenotes](casenotes)<br>
[The licences and other details](licence)<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#a-note-on-spelling-licence-or-license)<br>
[1. Introducing the GitHub Wiki](01-Introducing-the-GitHub-Wiki)<br>
|
| Table 12.2 β A simplified table of contents |
These are just standard markdown links covered in section 9.4, they are in the form:
|
ββ |
If the link is just to a Wiki page (it will load at the top of the page), this is simplified to:
|
ββ |
The HTML equivalent is:
| HTML and GitHub output |
|---|
|
|
     <a href="home">Home</a><br>
     <a href="casenotes">Casenotes</a><br>
     <a href="licence">The licences and other details</a><br>
       <a href="licence#the-licence">The Licence</a><br>
       <a href="licence#why-did-i-choose-the-mit-licence">Why did I choose the MIT Licence?</a><br>
       <a href="licence#permissive-licences">Permissive licences</a><br>
       <a href="licence#copyleft-licence">Copyleft licence</a><br>
       <a href="licence#limiting-liabilities">Limiting liabilities</a><br>
       <a href="licence#which-licence-to-use">Which licence to use?</a><br>
       <a href="licence#a-note-on-spelling-licence-or-license">A note on spelling</a><br>
  <a href="01-Introducing-the-GitHub-Wiki">1   Introducing the GitHub Wiki</a><br>
   <a href="01-Introducing-the-GitHub-Wiki#13creating-a-wiki-for-a-repository">1.3     Creating a Wiki</a><br>
|
|
|
|
βββββHome βββββCasenotes βββββThe licences and other details β 1β βIntroducing the GitHub Wiki |
| Table 12.3 β The basic table of contents in HTML |
Again, these are in the standard HTML format for a link to a point on a page:
|
ββ |
The #headingName can be omitted if linking to the top of the page
In the above example (either Markdown or HTML) there are strings of special space characters at the start of each line (an example is shown below):
| Markdown and GitHub output |
|---|
|
|
   [1.3.1  The first page]...
|
| Table 12.4 β Special space characters in a TOC |
These are used to indent the links so that they all line up, the alignment is as follows:
|
| Figure 12.2 β Table of contents alignment in a sidebar |
|---|
The general arrangement is that the chapter numbers all align on the left edge (with allowances for a collapsible area arrow, see section 12.4), this is shown by the solid pink line.
Section and subsection numbers are indented one numerical character (to align with a second digit of a chapter number), dotted pink line.
Chapter heading text is indented to align with the first full stop in a two-digit section number, dotted orange line.
If unnumbered chapter headings are used (CaseNotes and Home in the example of the previous section), these are indented to the same position, again, the dotted orange line.
Section and subsection texts are indented sufficiently to allow a number in the form nn.nn.nn (i.e. three, two-digit numbers) to precede the text, dotted green line.
These spacings are created by the strings of special space characters, e.g.:
βββ     
These force a correctly spaced gap before the heading number and heading text in the table of contents. By being inserted before the opening bracket, they do not form part of the heading itself, indenting the underline bar that indicates a clickable link.
These special space characters just make everything line up correctly and give a pleasing appearance. They are used extensively within the PracticalSeries Wikis and are discussed further in section 16.6.
Content within Markdown pages can be made collapsible (effectively hidden from view until clicked). Such content is often used within tables of contents, but can also be used for any text and even images.
The following shows two examples of collapsible content:
An example of lorem ipsum
Lorem ipsum dolor sit amet, consectetur adipiscing elit. In consectetur tortor a tortor ornare, non pretium diam faucibus. Morbi ut mollis dolor, nec pretium tellus. Suspendisse ornare neque placerat orci aliquam, eu sodales dui blandit.A picture of Henry
|
| Figure 1.1 β Henry the dog |
|---|
Clicking either of the two right-pointing arrows above will display the hidden content (shown open below):
An example of lorem ipsum
Lorem ipsum dolor sit amet, consectetur adipiscing elit. In consectetur tortor a tortor ornare, non pretium diam faucibus. Morbi ut mollis dolor, nec pretium tellus. Suspendisse ornare neque placerat orci aliquam, eu sodales dui blandit.A picture of Henry
|
|
| Figure 1.1 β Henry the dog |
|---|
When the content is expanded, the arrows point downwards (clicking the arrow again collapses the content once more).
Collapsible content is only possible with HTML, the code behind the first βlorem ipsumβ example above is:
| HTML |
|---|
|
|
<details><!-- START OF COLLAPSIBLE AREA -->
<summary>An example of lorem ipsum</summary><!-- VISIBLE TEXT -->
<!-- HIDDEN CONTENT -->Lorem ipsum dolor sit amet, consectetur adipiscing elit. In consectetur tortor a tortor ornare, non pretium diam faucibus. Morbi ut mollis dolor, nec pretium tellus. Suspendisse ornare neque placerat orci aliquam, eu sodales dui blandit.
</details><!-- END OF COLLAPSIBLE AREA -->
|
| Table 12.5 β HTML for collapsible content |
The format for any collapsible content is:
| HTML |
|---|
|
|
|
|
The
The
Everything else between the
Note
There should only be one <summary> tag per <details> tag, if more than one is included, only the first will be displayed, subsequent entries will be shown as unordered list points
For completeness, the HTML for the second βHenryβ picture is:
| HTML |
|---|
|
|
<details><!-- START OF COLLAPSIBLE AREA -->
<summary>A picture of Henry</summary><!-- VISIBLE TEXT -->
<table align="center"><tr><td><!-- HIDDEN CONTENT -->
<img width="400" src="11-0000/02-images/figm-99-01.png" alt="Henry">
</td></tr>
<tr><th align="center"><sup>Figure 1.1 — Henry the dog</sup></th></tr>
</table>
</details><!-- END OF COLLAPSIBLE AREA -->
|
| Table 12.6 β HTML for collapsible image in a table |
By default, collapsible areas are closed when a page loads, it is possible to force a collapsible area to default to the expanded state by using the
| HTML and GitHub output |
|---|
|
|
<details open><!-- START OF COLLAPSIBLE AREA -->
<summary>An example of lorem ipsum</summary><!-- VISIBLE TEXT -->
<!-- HIDDEN CONTENT -->Lorem ipsum dolor sit amet, consectetur adipiscing elit. In consectetur tortor a tortor ornare, non pretium diam faucibus. Morbi ut mollis dolor, nec pretium tellus. Suspendisse ornare neque placerat orci aliquam, eu sodales dui blandit.
</details><!-- END OF COLLAPSIBLE AREA -->
|
|
|
An example of lorem ipsumLorem ipsum dolor sit amet, consectetur adipiscing elit. In consectetur tortor a tortor ornare, non pretium diam faucibus. Morbi ut mollis dolor, nec pretium tellus. Suspendisse ornare neque placerat orci aliquam, eu sodales dui blandit. |
| Table 12.7 β An expanded by default collapsible area |
This causes the hidden text to be expanded by default when the page loads (clicking the arrow will close the expanded area as normal).
There are certain restrictions with the
It is not possible to put Markdown links (or indeed any Markdown formatting, not even **) inside a <summary> tag.
Any link or formatting that is required inside the
HTML can be used in the
The most widely used application of collapsible content is to manage tables of content.
Within the PracticalSeries Wikis, the TOC in the sidebar uses collapsible content to display only the chapter numbers and headings (the sections and subsections for each chapter being hidden). The contents for the current page are, however, expanded showing the section and subsections for that page.
The following is the sidebar TOC for chapter 2 of this Wiki:
|
| Figure 12.3 β Collapsible TOC |
|---|
To explain the collapsible TOC, consider the HTML (and Markdown) behind the chapter 2 TOC entry above:
| HTML and GitHub output |
|---|
|
|
<details open><!-- SECTION 02 -->
<summary><a href="02-Cloning-a-Wiki">2   Cloning a Wiki</a>
</summary><!-- BLANK LINE BELOW -->
   [2.1     Why clone a Wiki?](02-Cloning-a-Wiki#21why-clone-a-wiki-to-a-local-machine)<br>
   [2.2     How to clone a Wiki](02-Cloning-a-Wiki#22how-to-clone-a-wiki-to-a-local-machine)<br>
   [2.3     Pushing changes to GitHub](02-Cloning-a-Wiki#23pushing-wiki-changes-back-to-github)<br>
   [2.3.1  Configuring the Git credentials](02-Cloning-a-Wiki#231configuring-the-git-username-and-email-address)<br>
   [2.3.2  Commit and synchronise to GitHub](02-Cloning-a-Wiki#232committing-the-changes-and-synchronising-with-github)<br>
</details><!-- END OF COLLAPSIBLE AREA -->
|
|
|
| Table 12.8 β HTML for collapsible TOC |
This collapsible TOC is simply a collapsible content area that contains links in a similar fashion to the basic TOC in section 12.1.
The only differences being that the visible link contained within the
The blank line after the
Once collapsible TOCs have been created for each chapter (in a particular sidebar), they can be copied en-masse to all other sidebars (all sidebars have the same contents allowing navigation to any page in the Wiki).
The only distinction between the sidebars, is that the TOC for the chapter associated with the current page should be set to
TOCs can be inserted directly into HTML table (they can be inserted in to Markdown tables too, but Markdown tables require a heading row which isnβt required with a TOC).
| HTML and GitHub output |
|---|
|
|
<table align="center">
<tr>
<td width="425" valign="top">
<details><!-- SECTION 01 -->
<summary><a href="https://github.com/practicalseries/GitHub-Wiki-Design-and-Implementation/wiki/01-Introducing-the-GitHub-Wiki">1   Introducing the GitHub Wiki</a>
</summary><!-- BLANK LINE BELOW -->
       [A note by the Author](01-Introducing-the-GitHub-Wiki#a-note-by-the-author)<br>
   [1.1     What are GitHub Wiki pages?](01-Introducing-the-GitHub-Wiki#11what-are-github-wiki-pages)<br>
   [1.2     Understanding the Wiki pages](01-Introducing-the-GitHub-Wiki#12understanding-the-wiki-pages)<br>
   [1.3     Creating a Wiki for a repository](01-Introducing-the-GitHub-Wiki#13creating-a-wiki-for-a-repository)<br>
   [1.3.1  Creating the first Wiki page](01-Introducing-the-GitHub-Wiki#131creating-the-first-wiki-page)<br>
</details>
</td>
<td width="425" valign="top">
<details><!-- SECTION 02 -->
<summary><a href="02-Cloning-a-Wiki">2   Cloning a Wiki</a>
</summary><!-- BLANK LINE BELOW -->
   [2.1     Why clone a Wiki?](02-Cloning-a-Wiki#21why-clone-a-wiki-to-a-local-machine)<br>
   [2.2     How to clone a Wiki](02-Cloning-a-Wiki#22how-to-clone-a-wiki-to-a-local-machine)<br>
   [2.3     Pushing changes to GitHub](02-Cloning-a-Wiki#23pushing-wiki-changes-back-to-github)<br>
   [2.3.1  Configuring the Git credentials](02-Cloning-a-Wiki#231configuring-the-git-username-and-email-address)<br>
   [2.3.2  Commit and synchronise to GitHub](02-Cloning-a-Wiki#232committing-the-changes-and-synchronising-with-github)<br>
</details>
</td></tr>
</table>
|
It looks like this:
1β βIntroducing the GitHub Wikiββββββ A note by the Author |
|
| Table 12.9 β TOC in a table | |
|---|---|
The code for the collapsible TOC is the same as in the previous section (it starts and ends with the <details> tags).
Around this is the code for a one-row, two-column table.
The only thing of note here is that each cell is set to a width of 425 px to make the column widths equal and each is vertically aligned to the top, this stops the alternate column from centring vertically when one TOC is expanded and the other isnβt.
Footnotes are a slightly peculiar topic for the following reason:
GitHub Markdown has a structure for footnotes that works in Markdown files in a repository (a README.md file for example); the same structure does not, however, work in Wiki Markdown files.
In a repository Markdown file a footnote is indicated by entering [^nnn], where nnn is a unique identifier (usually a number indicating the number of the footnote).
The footnote text is given at some other point in the file with the format [^nnn]: FootnoteText.
Here is an example:
| Markdown and GitHub output |
|---|
|
|
The LOX pump delivered fuel at the rate of 24,811 gallons per minute [^1] and the kerosene from the tankage to the combustion chamber at the rate of 15,741 gallons per minute.
[^1]: it would have filled a swimming pool twenty-five feet long, ten feet wide, and six feet deep in twenty-seven seconds.
|
| Table 12.10 β A typical footnote in a repository Markdown file |
It looks like this in a repository README.md file:
|
| Figure 12.4 β A footnote in a repository Markdown file |
|---|
The footnote reference appears as a superscript 1 in brackets, point β above. The footnote itself appears at the end of the page, point β‘ (irrespective of where the footnote text is entered on the page). Clicking the footnote reference, point β , navigates to the footnote text, clicking the return emoji, point β’, navigates back to the reference point.
Putting exactly the same code in a Wiki Markdown file does this:
|
| Figure 12.5 β The same footnote in a Wiki Markdown file |
|---|
Here, the footnote formatting is ignored and the entries appear as literal text.
I donβt know why footnotes work in repository Markdown files, but not in Wiki Markdown files, there doesnβt seem to be any explanations online either.
So what to do?
I want to use footnotes; they lend themselves to my style of writing. So I came up with my own version. It uses HTML anchor points, links and the note alert.
My version of the above footnote looks like this:
π½π½π½π½π½π½
The LOX pump had to deliver fuel at the rate of 24,811 gallons per minute and the kerosene from the tankage to the combustion chamber at the rate of 15,741 gallons per minute.
Note
π 1βIt would have filled a swimming pool twenty-five feet long, ten wide and six deep in twenty-seven seconds.β©
πΌπΌπΌπΌπΌπΌ
Breaking it down it looks like this:
|
| Figure 12.6 β PracticalSeries footnote in a Wiki Markdown file |
|---|
This has a footnote reference (albeit with a diamond instead of the brackets), point β above. The footnote itself, point β‘, is a note type alert (see section 8.6); this contains the footnote reference, point β’ and a return link, point β£, clicking either of these links back to the original footnote reference.
So how does it work?
This is the code behind it
| HTML and GitHub output |
|---|
|
|
The LOX pump had to deliver fuel at the rate of 24,811 gallons per minute<a name="rn-01" href="#fn-01"><sup>π 1</sup></a>
and the kerosene from the tankage to the combustion chamber at the rate of 15,741 gallons per minute.
> [!NOTE]<!-- π‘FOOTNOTE CONTENT -->
> <a name="fn-01" href="#rn-01"><sup>π 1</sup></a> It would have filled a swimming pool twenty-five feet long,
ten wide and six deep in twenty-seven seconds.<a href="#rn-01">β©</a>
|
|
|
|
The LOX pump had to deliver fuel at the rate of 24,811 gallons per minuteπ 1 and the kerosene from
|
| Table 12.11 β A PracticalSeries footnote in a Wiki Markdown file |
Examining the first bit, the footnote reference, it looks like this:
βββ<a name="rn-01" href="#fn-01"><sup>π 1</sup></a>
And has the general format:
βββ<a name="returnID" href="#footnoteID"><sup>VisibleText</sup></a>
Firstly, returnID and footnoteID must be unique within the page (I use rn-xx for the returnID and fn-xx for the footnoteID, I keep the number xx the same for both and increment by 1 for each successive footnote on the page).
The name="returnID" sets the return point from the footnote text, the href="#footnoteID" is the link to the footnote text (see section 9.5 for full details of linking to anchor points). The VisibleText is simply what is displayed as the footnote link (in this case it is in superscript).
The footnote itself has to be positioned within the Markdown file. I tend to position them at the end of the page within which they occur.
The footnote itself is a Markdown note alert (see section 8.6 for full details), this displays the blue βΉ in a circle and the note caption and puts a blue line down the left-hand side of the footnote (again see section 8.6).
The first part of the footnote shows the same VisibleText as the footnote reference above (a blue diamond with a number), this time the code is:
βββ<a name="fn-01" href="#rn-01"><sup>π 1</sup></a>
And has the general format:
βββ<a name="footnoteID " href="#returnID "><sup>VisibleText</sup></a>
The, returnID and footnoteID must be match those used in the footnote reference.
The name="footnoteID" sets the anchor point from the footnote text (this is linked to in the footnote reference), the href="#returnID" is the return link to the footnote reference in the body text. The VisibleText is simply what is displayed as the footnote link (it is identical to the footnote reference).
This anchor link is followed by the text of the footnote which terminates with:
βββ<a href="#rn-01">β©</a>
And has the general format:
βββ<a href="#returnID "><sup>VisibleText</sup></a>
This is just a return link to the footnote reference in the body text, this time with a return emoji.
|
|
|
|
|
|
The PracticalSeries of Publications β Copyright Β© 2025 Michael Gledhill
β¬οΈ Top β | β [email protected] β | β PracticalSeries of Publications β | β Main repository