Home

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:

		^{List 1 — Scope of this Wiki}
	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

⬆️ 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”.↩