05 Markdown, GitHub Markdown and HTML

5Markdown, GitHub Markdown and HTML

This section and those following cover the standard markdown and GitHub Flavoured Markdown (GFM) formatting techniques available within Wiki pages. It also covers the use of Hypertext Markup Language (HTML) within Wiki pages.

HTML can be used within Wiki pages to a limited extent (GitHub restricts “sanitises” the range of HTML tags and attributes that can be used on its pages), but even this restricted form of HTML within Wiki pages is very useful and generally leads to better formatting on a Wiki page.

5.1Some useful Markdown sites

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:

   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.

As an aside, the GitHub documentation for Wikis itself 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

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 turn out 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).

I haven’t used this yet, I don’t know enough about the SVG content language, but it is intriguing.

⬆️ Top

---

5.2An overview of Markdown

Markdown is a lightweight Markup language (It’s a bit stupid I know, Markdown, Markup… I blame the Linux people.).

Markup languages are things like HTML, they use a lot of tags and a complex grouping of styles and elements to provide a very flexible arrangement for formatting text on web pages.

Markdown is a simpler version of Markup, it uses plain text with certain specific characters that in some way format the text (i.e. make headings, tables, bold, italic &c.). Markdown is not as flexible as markup. Comparing Markdown with HTML, Markdown does not provide the intricate styling available to HTML, but it is much easier to read, understand and use.

Markdown is not a programming language (in the sense that HTML is) and it does not require the same level of understanding (Markup languages like HTML, due to their complex syntax and tags, require more time and effort to understand and to write and modify the content of a page or document).

Markdown is designed to be easy to learn and accessible for beginners, but is also limited in what can be achieved. It is not a replacement for Word processors or HTML.

Markdown was created by John Gruber in 2004 and is the default mechanism for documenting repositories in GitHub (any file on GitHub that ends with the .md extension is a Markdown file). The following sections explain in some detail how Markdown and the GitHub version of Markdown (called “GitHub Flavoured Markdown” or GFM) work.

Markdown is not generally application specific; it is designed to be platform independent. In our case though, we are using Markdown because that is what GitHub requires us to do for its Wiki pages (yes, there are other languages: AcsiiDoc, Creole, MediaWiki &c. but they are not widely used. Everybody uses Markdown).

⬆️ Top

---

5.3How Markdown works

Markdown is written in a plain text file with the extension .md. Markdown files are normally created in a text editor (in my case this is Microsoft’s Visual Studio Code or more commonly just VS Code). The following is an extract of the Markdown file for this page:

Figure 5.1 — A Markdown file

*It may be fair to say that my Markdown files might be considered, er... different. They don't look like everybody else’s. Don't worry, you'll get used to them.

Markdown files are not “what you see is what you get” (WYSIWIG) files like Word files, it is encoded plain text.

So what happens once you have written a Markdown file? Well, in the case of GitHub Wikis, GitHub uses a Markdown processor (sometimes called a parser) which converts the plain text in the .md into HTML. This HTML is then made available via the GitHub website to any web browser, as shown:

Figure 5.2 — A visual representation of the Markdown process

For the purposes of producing a GitHub Wiki, all that is needed is the first part — it is necessary to write the Wiki content. GitHub does the rest.

GitHub helps the writing process (on its website), by allowing the written .md file to be previewed. Within VS Code, the extension: Markdown Preview Enhanced does the same thing.

⬆️ Top

---

5.4Markdown flavours

Virtually every implementation of Markdown uses a slightly different version, each with its own features and variations. These are referred to as “flavours” of Markdown (I know, the terminology is awful).

In the case of GitHub, the only thing we need to know about is GitHub Flavoured Markdown (GFM).

5.4.1GitHub Flavoured Markdown (GFM)

There is a common set of rules for basic Markdown, these include adding headings, images, links, emphasis &c. This is called basic Markdown syntax.

GitHub needed a bit more than this; they want to include tables, code fragments, flow charts, task lists and links to GitHub elements. These additions are referred to as GitHub Flavoured Markdown or GFM.

Finally, there is the extended Markdown syntax, this allows the use of certain HTML tags directly within the Markdown file.

The following sections give full explanations of how each of these things work and the syntax and mechanisms involved.

⬆️ Top

---

5.5HTML and Markdown

The fact the Markdown is rendered into HTML, and the fact that Markdown by itself is lacking in certain areas, probably explains why most Markdown processors allow certain elements of HTML to be used directly in the Markdown text.

GitHub is no exception and it supports a wide range of HTML tags and attributes. In most cases, everything that can be done with Markdown can be replicated using HTML tags and attributes.

This guide is not intended to be an instruction manual for HTML (although I do have one here: https://www.practicalseries.com/1001-webdevelopment/index.html), but wherever I give an example of how to do something with Markdown, I also include the HTML equivalent.

In many cases (tables for example), HTML is much easier and more flexible than Markdown.

The PracticalSeries Wikis use HTML a lot, particularly where tables are concerned (see section 10).

It seems to me that using HTML in Markdown is frowned upon; I see the point: Markdown is supposed to be easy to read and adding HTML makes it harder. It’s a fair point; the trouble is HTML is needed to make Markdown do what you want it to do. It isn’t the 1990s anymore and online documentation has come a long way. Markdown needs to be more sophisticated in what it will allow ${\large\color{#C00000}\text{(changing\ the\ font\ colour\ doesn’t\ seem\ too\ outrageous\ to\ me)}}$ . Until Markdown is better, people will find ways around the restrictions.

GitHub needs to either bite the bullet and embrace HTML or make its version of Markdown better

${\large\color{#C00000}\text{p.s.\ If\ you\ want\ to\ know\ how\ I\ got\ the\ red\ text\ in\ there,\ see}}$ section 14.6.

⬆️ Top

---

5.5.1HTML with GitHub Flavoured Markdown

GitHub tolerates HTML in its Wiki pages (I think reluctantly). It is however, quite strict about what it will allow. It does not, for example (and much to many people’s annoyance), allow the <style> tag, it thinks it is dangerous: “not allowed for security reasons”. It’s annoying because the style tag give access to a lot of useful things like text alignment. It also means it’s practically impossible to change the font colour.

Tip

Although GitHub doesn’t allow the style tag or the use of CSS on its Wiki pages, it does allow the use of SVG images. I hadn’t realised before I started this that SVG files can actually contain HTML and CSS code that is executed when the image is loaded. This gives a workaround (albeit a very awkward one) to having CSS on a Wiki page. It is also a glaring hole in GitHub’s security. There are several articles on the subject, this is one: https://pragmaticpineapple.com.

When GitHub detects HTML tags in a Markdown page, it “sanitises” the HTML by stripping out anything it doesn’t like. Effectively there is a white list for tags that GitHub will allow. Similarly, it also removes certain attributes it doesn’t like if it finds them attached to a tag.

In addition, there are some tags and attributes which, while not officially whitelisted by GitHub, work perfectly well. There is a useful page https://github.com/bryanbraun/github-wiki-html-test/wiki that runs through all the main HTML tags and tries them on a GitHub wiki page.

The following tables summarise my findings:

GFM blacklisted HTML tags     

The tags that GitHub specifically does not allow (BLACKLIST) are:

<audio> <font> <form> <iframe>	<input> <noembed> <noframes> <output>	<plaintext> <script> <select> <style>	<textarea> <title> <video> <xmp>
Table 5.1 — GitHub Markdown BLACKLISTED HTML tags

GFM whitelisted HTML tags     

The tags that GitHub specifically supports (WHITELIST) are (by tag type):

Anchor:	<a>
Breaks:	<br> <hr>
Headings:	<h1> <h2> <h3> <h4> <h5> <h6>
Images:	<img>
Lists:	<ol> <ul> <li> <dl> <dt> <dd>
Tables:	<table> <thead> <tbody> <tfoot> <tr> <td> <th>
Text (block):	<p> <div> <blockquote> <details> <summary> <pre>
Text (inline):	<b> <i> <strong> <em> <code> <ins> <u> <del> <s> <sup> <sub> <samp> <q> <var>
Table 5.2 — GitHub Markdown WHITELISTED HTML tags

GFM HTML tags — the grey area     

Tags that are not in either the blacklist or the whitelist are a grey area. Things like <section> work, things like <option> don't.

A rough rule of thumb is that harmless or informative static tags like <section> and <figure> work, tags that have some form of live data or have an interaction or excesive influence like <time> and <option> do not work.

GFM whitelisted HTML attributes     

In terms of HTML attributes, the following are WHITELISTED:

abbr accept accept-charset accesskey action align alt axis border cellpadding cellspacing char charoff charset checked cite clear cols	colspan color compact coords datetime dir disabled enctype for frame headers height href hreflang hspace ismap itemprop itemscope	itemtype label lang longdesc maxlength media method multiple name nohref noshade nowrap prompt readonly rel rev rows rowspan	rules scope selected shape size span src start summary tabindex target title type usemap valign value vspace width
Table 5.3 — GitHub Markdown WHITELISTED HTML attributes

⬆️ Top

---

5.5.2PracticalSeries and Markdown

I haven’t invented my own Markdown “flavour”, but I have discovered various workarounds and techniques that give consistency and a visual style to the PracticalSeries Wiki pages, things like the link to the top of the page that appears at the end of each section:

⬆ Top

---

It explains things like the collapsible content tables in the sidebar, badges and buttons, navigation bars a consistent approach to images, tables and captions &c.

I cover all of these “conventions” in section 16.

⬆️ Top

---

5.6Markdown difference between files

Surprisingly, there are difference between Markdown files used in a GitHub Wiki and that used in repository Markdown files (such as README.md).

I don’t really have an explanation why this should be the case; to my mind, I would have thought they used the same Markdown engine.

Anyway, here are the differences I’ve found

❶	Footnotes, these work in repositories, but not in Wiki markdown, see section 12.6
❷	Repository Markdown does not support the <u> tag for underlining text (you have to use the <ins> tag instead) see section 6.7
❸	HTML in GitHub Markdown does not support the &numsp;, &emsp13;, &emsp14;, &puncsp; or &hairsp; (and other) escape sequences. Repostitory HTML has no problems section 7.2.1
	List 5.1 — List of Markdown differences

That’s it, that’s all I’ve found.

If I find any others, I’ll add them to this list.

---