Home.md

Home        The GitHub Wiki        What does this guide cover?        A note by the Author    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 A    Unicode and HTML escape    A.1     HTML Escape codes, full list    A.2     Non-functional escape sequences 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 D   3D Model of a Sierpinski cube        3D Sierpinski cube E    Template        COMMENT FIELDS        HEADINGS        TABLES        FIGURES        LISTS        TASK LISTS        CODE FRAGMENT        FORMULAE        LINKS        BUTTONS        ALERTS        COLOURED TEXT        INDEX NUMBERS        END OF SECTION        FOOTNOTE        END OF PAGE

⬆ Top of page⬇️ End of page

GitHub Wiki — Design and Implementation

These Wiki pages are designed to be a full guide to developing and implementing a GitHub Wiki documentation project.

It originally started as a template that stored a set of GitHub Wiki page examples that I could quickly access and copy to the other Wiki pages in a repository.

In doing so, I realised that there are various techniques (some might call them hacks) to get around the limitations of GitHub Flavoured Markdown (GFM), I also realised that while many features of Wikis are documented by GitHub^💠1, the explanations in the GitHub documentation don’t always cover everything (or at least the explanations can be hard to find) and you end up looking around all sorts of websites to find the information.

The upshot of all this is that what started as a simple template page has become a bit of a guide for producing GitHub Wiki files. I hope you find it useful.

There is also a pdf version of the Wiki that you can download and use. It’s available here for free:

⬆️ Top

---

What does this guide cover?

This guide covers pretty much everything you need to know about creating and manag-ing a GitHub Wiki for a repository.

It goes from the very basics of creating a page from scratch to the more complicated arrangement of a folder structure, independent sidebars and footers for each page and on to the vagaries of Git Flavoured Markdown, the use of HTML and the various techniques and workarounds that are required to make Wiki pages look good and respond properly. It covers the following topics:

	Creating a Wiki for a repository   Cloning a Wiki to a local machine   Understanding how Wiki pages are stored and structured   Basic concepts of a Wiki page   Sidebars and footers   Imposing a folder structure on a Wiki   Creating different sidebars and footers for individual pages   Understanding Markdown, Git Flavoured Markdown and HTML for Wiki pages   Basic Markdown:
		Body text   Paragraphs   Line breaks   Horizontal lines   Emphasis (bold, italic, underline, strikethrough)   Lists (numbered, unnumbered, nested and combinations)   Block quotes   Headings   Links   Images   Escape characters   Using special space characters
	Extended Markdown (Git Flavoured Markdown):
		Footnotes and alerts   Links to headings   Task lists   Tables of contents   Tables (Markdown)   Code fragments (with syntax highlighting)   Formulae and LaTeX   Built in diagrams (Mermaid) and interactive maps   Links by reference   Emojis
	HTML within Markdown:
		Names and anchor points   Tables (HTML)   Tables vertical alignment   Collapsable content   Links with HTML   Images with HTML   Buttons   Navigation bars
	Differences between Wiki pages and standard GitHub Markdown pages   PracticalSeries conventions — How to make the Wiki look good:
		Sidebars and footers, best practice   IO Badges   Conventions for folders, image storage and data storage   Links to top, bottom and other points on a page   Making footnotes work on Wiki pages
	Wiki revision control, commits and rebasing   Examples, templates and good working practices   Appendices of HTML escape codes, emojis and character
		List 1 — Scope of this Wiki

⬆️ Top

---

A note by the Author

GitHub Wiki pages are generally written in Markdown (like repository README.md files).

I’ll say right from the start that I’m not the biggest fan of Markdown. I understand the idea, it’s designed to be an easy way to format plain text and make it into a more readable document. It’s easier to understand than the HTML (hyper-text markup language) and CSS (cascading style sheets) used to create web pages, but has roughly the same purpose.

The reason I’m not the biggest fan is that Markdown itself isn’t good enough for today’s documentation requirements. We’re all used to responsive websites with distinct fonts and clever images and animations. Markdown feels a bit like turn of the century websites and is very restrictive in terms of what you can do.

This may be done on purpose, GitHub in particular (I think) wants repository documentation to conform to certain styles and have a common appearance (and I have some sympathy for this approach, after all it’s their website and they can impose whatever restrictions they want).

The problem is that basic Markdown doesn’t support all the things that are needed to format a document properly for software documentation. This means that things get added and we have GitHub Flavoured Markdown which supports things such as code fragments, task lists &c. This in itself is also not sufficient and now GitHub Markdown supports certain HTML tags to allow better formatting.

The whole thing is a bit of a mess and is actually quite badly documented. It’s pretty difficult to find out which HTML tags are allowed or not allowed by GitHub. You will spend a lot of time doing Google searches, looking around on the Stack Overflow (https://stackoverflow.com/) website and coming across phrases like “syntactic sugar^💠2”.

To overcome some of these problems, I’ve put together descriptions of the things that I’ve discovered and the various work arounds I've found, I’ve also listed some of the more useful sites that I’ve come across in my research (clearly, I’m not the only one who found the lack of documentation frustrating).

In a later section I’ve put together a series of conventions, examples and templates that I use on the PracticalSeries Wikis these conventions cover most of the things you will want to do within Wiki pages.

Michael Gledhill Chester — January 2025

⬆️ Top

---

Footnotes:     

Note

^💠1 The GitHub documentation is located here:

   https://docs.github.com/en/enterprise-cloud@latest

Select Get started and then Writing on GitHub.

There is also a style guide for GitHub documents (this is GitHub’s own style guide for its own documentation), and it has some useful tips and conventions:

   https://docs.github.com/en/contributing

As an aside, the GitHub documentation is actually a repository in it's own right (it can be useful to see how GitHub do things). You can find it here:

   https://github.com/github/docs/tree/main/content ↩

Note

^💠2 Syntactic sugar: a horrible expression that refers to features of a programming language that makes the code easier to read. I suppose along the lines of “It sweetens the deal”.↩

---

The PracticalSeries of Publications — Copyright © 2025 Michael Gledhill

⬆️ Top   |   mg@practicalseries.com   |   PracticalSeries of Publications   |   Main repository