Understanding CommonMark and GFM in the Context of iOS Markdown Rendering

The highest level explanation of GitHub Flavored Markdown in the context of iOS markdown rendering.

To start, lets break it down.

What is Markdown

Markdown is a markup language that uses plain text formatting syntax to allow it to be easily converted to HTML. This means you can write content in a more intelligible way (no more <> everywhere) that can be easily displayed in a prettified HTML form.

Markdown is intended to be as easy-to-read and easy-to-write as is feasible.

What is a Markdown ‘spec’?

Markdown was originally created by John Gruber in 2004, but there are many different implementations — or flavors — of it that exist today. Each of these specifications define how things written in markdown will turn into HTML, and they each vary slightly.

CommonMark vs. GitHub Flavored Markdown

CommonMark and GitHub Flavored Markdown (GFM) are both flavors of markdown.

GFM is a strict subset of CommonMark, taking the original CommonMark spec and adding support for tables, strikethroughs, auto-links, and task lists — among other small tweaks. You may already be familiar with how these features work, because they have been supported by GitHub for years now.

Why CommonMark?

The reason to choose to compare CommonMark to GFM, and the reason that GitHub built GFM as a subset to CommonMark, is cmark — the super powerful C implementation of the CommonMark spec.

cmark can render a Markdown version of War and Peace in the blink of an eye (127 milliseconds on a ten year old laptop, vs. 100–400 milliseconds for an eye blink)

By forking and extending cmark, GitHub has built upon a sturdy parsing foundation and added to it just what it needed to render its flavor of markdown properly on GitHub.

CommonMark, GFM, and Down for iOS

So we have some powerful players in the world of markdown parsing and rendering in cmark and cmark-gfm — a solid start for our parsing needs in Swift. And thanks to the tireless efforts of the Open Source community, libraries already exist to convert markdown to HTML using cmark.

The library I’m currently using to do this elegant task is Down.

Down renders markdown using the CommonMark spec in Swift, and has an excellent API flexible enough for use in almost any iOS app needing to convert markdown or display parsed markdown in a nice HTML view.

But Wait, No Tables?

Here is the issue. The developers behind down have a very specific purpose — to implement a Swift markdown processor based on cmark. Variations, like GFM, are specifically not supported.

What the iOS markdown-rendering community needs is the hero who wants to create their own GFMDown library, and swap the cmark foundation of Down out for cmark-gfm.

I’m excited to learn more about cmark, GFM, and the process of parsing markdown as I continue down my path of discovery building my current markdown powered app. Let’s hope I can help pave the way towards a solid Swift library for GFM, but I can’t do it alone.

Please reach out if you know of an awesome GitHub-flavored libraries in Swift. Or if you’ve got the gusto, fork Down and build it yourself!