This repository is a result of creating various GitHub Wikis for the PracticalSeries repositories.
It originally started as a template repository that stored a set of GitHub Wiki page examples that I could quickly access and copy to the more relevant Wiki pages in this 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.
The full guide can be found on the Wiki pages for this repository, click the Wiki tab at the top of this page. Alternatively, follow this link:
https://github.com/practicalseries/GitHub-Wiki-Design-and-Implementation/wiki
This guide covers pretty much everything you need to know about creating and managing 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:
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
| Table 1 — Scope of this repository | ||
|---|---|---|
The full guide can be found on the Wiki pages for this repository, click the Wiki tab at the top of this page. Alternatively, follow this link:
https://github.com/practicalseries/GitHub-Wiki-Design-and-Implementation/wiki
GitHub Wiki pages are generally written in Markdown (like this readme file).
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💠3 (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 — October 2024
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:
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”.↩
Note
💠3 The following are some useful sites that cover both the basics and the more esoteric aspects of Markdown.
Firstly (for what it is worth), the official GitHub specification for GitHub flavoured markdown (GFM):
https://github.github.com/gfm/
This is the official specification for what is supported by GFM, it is to a large extent impenetrable and is difficult to understand. Section 4.6 for example, discusses the use of the HTML tag <style> (example 114) and seems to imply it is supported by GFM. Similarly the <script> tag is used in example 140; both however, are not supported by GFM. Again, the document is confusing — I may be missing something.
Next is a much more useful site:
https://www.markdownguide.org/
This site is developed by Matt Cone and is a comprehensive list of what Markdown can do. The only slight problem is that is covers various different types of Markdown alternatives (GitHub Flavoured Markdown is only one of many) and the different variations all support different levels of complexity and function, they are all effectively different version of Markdown.
This site was my goto reference for Markdown and the use of HTML within GitHub flavoured markdown.
The following covers the features of Markdown in a concise form, it was written by John Gruber who, it so happens, invented Markdown:
https://daringfireball.net/projects/markdown/basics
There is one other site listed here that is a bit of an oddball, but I think it may turnout to be quite useful, it’s certainly clever:
https://pragmaticpineapple.com/adding-custom-html-and-css-to-github-readme/
GitHub Flavoured Markdown supports the use of SVG images. Now it turns out that you can do quite a lot with the SVG format (SVG is really just a container for code that usually renders a graphical image in a vector format). SVG supports the use of a ForeignObject element and this element can contain HTML and also inline CSS, it is a way around the HTML restrictions imposed by GitHub (given their obsession with security, I’m surprised they allow it).↩