Markdown logo –The Markdown Mark by Dustin Curtis

Markdown Variants and History

Markdown is a markup language that I personally use on a regular basis for technical documentation at work. Its text is typically converted to HTML (which is also a markup language) for browsers to render. Its raw syntax is human readable; it is not convoluted like HTML, LaTeX or troff. However, it is not as feature rich as the aforementioned formats; it’s lightweight.

A Brief History

Circa 2002
Aaron Swartz released atx, a precursor to Markdown.
He later collaborated with John Gulber by providing ideas, feedback and testing for Markdown.
March 2004
John Gulber released Markdown: “a text-to-HTML formatting tool” written in Perl. He uses it to write his own blog articles.
Aaron Swartz rewrites html2text to covert HTML to plain text in Markdown format.
December 2004
Michel Fortin released PHP Markdown, an implementation of the text-to-html tool in PHP.
August 2006
John MacFarlane, a Professor of Philosophy, created the initial release of Pandoc (version 0.1). A tool written in Haskell for converting one markup language to another including Markdown and its variants.
May 2007
Fletcher T. Penney created MultiMarkdown (MMD) which extends the features from Gulber’s Markdown. It adds syntax to support tables, metadata, footnotes and more.
May 2008
John MacFarlane created a C implementation of the Markdown to HTML tool, PEG Markdown. It also has a couple of small extensions: footnotes and strikethrough.
Circa 2008
Michel Fortin created BabelMark, an online tool that compares how different implementations of Markdown converts text to HTML. John MacFarlane made his own version (BabelMark2) in 2012. Alexander Mutel in 2016 made BabelMark3 as the final successor.
Circa 2009
GFM, Github Flavoured Markdown forked from Gulber’s syntax, but changes how newlines and underscores are treated, and adds auto-linking.
November 2009
Thomas Leitner releases kramdown1, written in Ruby. With stricter defined syntax and support for common Markdown extensions.
Circa 2010
Natacha Kerensikova / Natacha Porté was not a fan of PEG Markdown and created their own C implementation of the Markdown to HTML tool, upskirt libsoldout2(.
February 2011
Fletcher T. Penney, remade MMD by forking John MacFarlane’s PEG Markdown.
April 2011
Vicent Martí the Principal Systems Engineer at GitHub, forked libsoldout to create Sundown. A web security focused Markdown parser, to use for rendering user submitted markdown documents on GitHub.
October 2011
Neil Williams a software developer at Reddit forked Sundown into Snudown and wrapped it to be used in Python so it can to be used to render Markdown on Reddit.
Circa 2012
Michel Fortin releases PHP Markdown Extra, an extension to PHP Markdown that include Header Id, Fenced Code blocks, tables, footnotes, and more.
October 2014
John MacFarlane, Martin Woodward, and Jeff Atwood set out to standardize Markdown specification 2 years prior and dubbed it Standard Markdown CommonMark. John Gulber, the original author of Markdown was invited to be part of this project, but declined to join. He was also very cross with its original name “Standard Markdown”.
March 2014
GitHub releases support for multiple markup languages, including Markdown. It uses Ruby written parser libraries. For Markdown it used RedCarpet, which is a Ruby wrapper library for Sundown (written in C).
January 2015
John MacFarlane released cmark, C implementation of CommonMark.
Nov 2016
GitHub forked CommonMark spec into GFM (Github Flavoured Markdown). Forked it’s C implementation cmark into cmark-gfm.
March 2017
GitHub switches Markdown renderer to CommonMarker, a Ruby wrapper for cmark-gfm.
March 2017
Fletcher T. Penney releases MultiMarkdown v 6.0, comes with a complete rewrite of the parser, and adds a few new features. It also depreciated some syntax, and is not CommonMark compliant.
January 2018
Yuki Izumi/Ashe Connor/Amelia Cuss released version 0.1.8 of Comrak. They have worked on this Rust port of cmark-gfm from scratch since November 2016.
Circa 2018
Reddit was redesigned and used a new Markdown parser: snoomark (or Reddit-flavored Markdown). It is a fork of Comrak. It mostly follows CommonMark and GFM syntax, with few Reddit specific compatibility quirks that deviate from CommonMark spec. These quirks exist so old posts are still correctly rendered. The parser is not open source like the others are.
December 24, 2023
CommonMarker 1.0.0 is released, and switched to wrapping Comrak instead of cmark-gfm into Ruby. This effectively switched what renderer GitHub uses.

Markdown variants

As you can tell from the timeline above, there’s quite a few variants of Markdown syntaxes and implementation. Some like Sundown have fallen out of use. Here’s a modern list of popular Markdown variants:

  1. Original Markdown 1.0.1, it defines the base syntax for all other variants. Its original software implementation has not been updated; it’s 20 years old, bare bones, and buggy. There is a rumoured update for it made in 2006 (version 1.0.2), but never released. John Gulber still uses it for his website blog posts to this very day, and the online demo tool is still up.
  2. CommonMark, a very well defined syntax spec for Markdown, with many compliant up to date implementations like cmark and commonmark.js.
    • Wordpress uses this, users can add “Markdown Block” to write CommonMark formatted text.
    • StackOverFlow uses this and extends it to include tags, spoilers, code syntax highlighting and tables. They used to use PageDown (forked from Showdown) before CommonMark.
    • Other popular implementations include:
  3. Github Flavoured Markdown (GFM), an extended spec of CommonMark, with many compliant up to date implementations like cmark-gfm and comrak. It adds filtering HTML tags, tables, strikethrough and check list into the spec.
    • GitHub clearly uses it. They use CommmonMarker, which is just a Ruby wrapper for comrak.It also has additional extensions like superscript, header ids, description lists, and footnotes.
    • Reddit uses their own variation of GFM called snoomark which is forked from comrak. However, it’s not 100% compliant with CommonMark for backward compability reason for its old posts.
    • goldmark which is compliant with GFM. It also includes support for definition lists and footnotes.
      • Hugo a static website builder, uses this.
  4. PHP Markdown Extra, PHP implementation of Markdown with additional syntax like tables, defition lists, and footnotes.
  5. kramdown, Ruby implementation of Markdown with additional syntax simlar to PHP Markdown Extra and Pandoc’s Markdown. Unlike others, it has no support for strikethrough.
    • Jekyll a static website builder, uses this.
    • webgen a static website builder, supports using this.
  6. MultiMarkdown (MMD), the original popular extented implemenation of Markdown. Now on version 6, it’s the most feature rich variant, but it also differs by syntax the most.
  7. Pandoc’s Markdown], yet another flavour of Markdown that is suprisingly feature rich, rivaling MMD.

So which one to use?

For writing content on online web platforms such as GitHub, StackOverFlow, Reddit, and Wordpress just use their respective extension of CommonMark.

If you are making your own platform where you have users who can submit their own Markdown text (where they can write comments), prioritise security. You don’t want to render comments with malicious code that could steal other user’s credentials. Use a regularly updated renderer that supports tag filtering, and pair it with HTML sanitation software. Using comrak (GFM) along with Ammonia is a good pairing.

You should also consider kind of content you will you write and what features you need. For example, if you need write mathematical equations out, you want to consider using kramdown, MultiMarkdown or Pandoc’s Markdown.

If you are making your own static website or blog (like the one you are reading now) where only you submit posts, you could consider using Jekyll or Hugo as static web site builders that have their own Markdown renderers.

What do I use?

For me it was a process of elimination. I tried one renderer after another, but something was wrong in the end result.

  • I tried MMD, but it has unfavourable strikethrough syntax. It uses --dashes-- instead of ~~tilde~~ for strikethrough.
  • I tried kramdown, but it doesn’t support ~~strikethrough~~.
  • I tried Comrak, but it doesn’t support definition list syntax without an extra blank line.

After trying out different renderers, I am currently using a CLI wrapper for goldmark. It succeeds in rendering the way I want it for this website.

Further Readings

Credits

Written by Val Efimov, published on March 10, 2024.

  1. Some renderers like kramdown and cmark are named with a lowercase starting character, despite being a proper noun. It seems to be a stylistic choice, similar to how “eBay” also breaks the gramatical rule. ↩︎

  2. The author re-named their renderer: “Eventually I renamed it to the more neutral and thematically-consistent name it currently has.” ↩︎