Flavour Guide
Behaviour differences across Markdown flavours.
Markdown does not have a single, authoritative version. Since John Gruber published the original specification in 2004, dozens of tools have implemented Markdown in their own way — adding features, resolving ambiguities differently, or extending the syntax for specific use cases. These variants are commonly called 'flavours'.
Most flavours share a common core: headings, paragraphs, lists, links, emphasis, and code all work the same way almost everywhere. The differences emerge when you reach for features beyond that core — tables, footnotes, task lists, maths notation, or diagrams — where each flavour makes its own choices about what to support and how.
Understanding flavours matters for two reasons.
The first is portability. A Markdown file written for one platform may not render correctly on another. A table written in GitHub Flavoured Markdown will display as a table on GitHub but appear as a jumble of pipe characters on a platform that does not support the GFM table extension. Knowing which flavour your platform uses helps you write with confidence and avoid surprises.
The second is choosing the right tool. Different flavours suit different purposes. CommonMark is the right choice when consistency across tools matters most. GitHub Flavoured Markdown is the natural choice for anything hosted on GitHub. Pandoc Markdown is built for authors producing finished documents — books, reports, or academic papers — where rich features like footnotes and citations are essential.
This chapter introduces each major flavour, explains where it came from and what it adds, and offers guidance on when to use it. The Flavour Support Cross-Reference at the end of the chapter lists every element covered in this book alongside its support status across all flavours — a useful reference when you need to check whether a specific feature will work in your environment.
Original Markdown
Original Markdown is the dialect defined by John Gruber and Aaron Swartz in 2004 — the starting point from which every other Markdown flavour grew. It introduced the syntax most people recognise today: headings with #, emphasis with *, links in square brackets, and code in backticks. Nearly ever...
CommonMark
CommonMark is a formally specified, unambiguous standard for core Markdown parsing. It was created to solve a fundamental problem with the original 2004 Markdown specification: John Gruber's definition left many edge cases undefined, which meant different tools produced different results from identi...
GitHub Flavoured Markdown
GitHub Flavoured Markdown (GFM) extends CommonMark with a small, well-chosen set of features designed for collaborative writing and project documentation. It adds tables, task lists, strikethrough text, and extended autolinks — and it restricts certain raw HTML elements. GFM was formally specified b...
Pandoc Markdown
Pandoc Markdown is the extended Markdown dialect used by Pandoc — a document conversion tool that transforms plain-text source files into finished outputs including PDF, EPUB, Word, and HTML. Where most Markdown flavours are tied to a specific platform or renderer, Pandoc Markdown is authoring-orien...
Markdown Flavour Support Cross Reference
Full flavour support tables for every language reference page. Each per-page table shows only four core flavours (Original Markdown, CommonMark, GitHub Flavored Markdown, Pandoc Markdown); the complete tables are kept here. When a new language reference page is added, its full table must be append...