Back to Blog
Reference 2026-04-26

Markdown Flavors Compared: CommonMark, GFM, MDX

Pick the right Markdown flavor for documentation, blogs, or content management.

Markdown is not one language; it is a family of dialects that happen to share a surname. John Gruber's original 2004 release was a Perl script and an informal description, and it left core questions unanswered: How do emphasis markers nest? How much indentation continues a list item? Is a blank line required before a nested block? Every implementation answered differently, which is why the same document can render three different ways on three platforms. Understanding the major flavors — and which one your toolchain actually speaks — eliminates a whole class of formatting surprises.

CommonMark: The Formal Baseline

CommonMark (2014, led by John MacFarlane of Pandoc fame) turned the informal description into a rigorous specification with over six hundred conformance examples and two reference implementations, cmark in C and commonmark.js. It nails down precisely the ambiguities that used to differ between parsers:

  • Exact emphasis rules: whether a delimiter opens or closes emphasis is decided by left- and right-flanking delimiter runs, which is why an intraword asterisk pair italicizes while space-surrounded asterisks stay literal
  • List continuation: content belongs to a list item if indented to the item's content column, not a magic four spaces
  • Seven distinct types of HTML blocks, each with its own start and end conditions
  • Precedence: link syntax beats emphasis, code spans beat everything inline

If your content must render identically across many tools, write to CommonMark and avoid anything it does not define.

Heading level one


=================
__bold__ and _italic_ and code

[link](https://example.com)
1. ordered item


   continuation, indented to the content column

GFM: CommonMark Plus What Developers Need

GitHub Flavored Markdown is formally a strict superset — GitHub publishes it as a spec that extends CommonMark with exactly five extensions: tables, task list items, strikethrough, autolinks, and the tagfilter that strips dangerous raw HTML tags. Footnotes, emoji shortcodes, and mentions are GitHub platform features layered on top, not part of the GFM spec, which matters when another "GFM-compatible" renderer refuses your footnotes.

|Column|Type|


|------|----|


|id    |int |
* [x] shipped


* [ ] pending
~~deprecated~~ and https://autolinked.example.com

One subtle divergence: in .md files GitHub follows the spec — a single newline is a soft break — but in issues and comments a single newline becomes a hard line break. Copying text between the two contexts changes its rendering.

MDX: Markdown That Compiles

MDX is not a markup dialect so much as a compilation target: each file becomes an ES module. You can import components, export values, embed JSX, and evaluate expressions inline:

import { Chart } from '../components/Chart';


export const data = [4, 8, 15, 16];
The total is {data.reduce((a, b) => a + b, 0)}.
<Chart values={data} />

The power comes with real costs. Raw HTML no longer passes through — angle-bracket content is parsed as JSX, so class must become className, unclosed tags like <br> are syntax errors, and a stray { starts an expression. A build error in one document can break the whole site build, and non-developer contributors lose the "it is just text" guarantee that made Markdown attractive. Choose MDX when documents genuinely need live components (interactive docs, design systems); choose GFM when they need to be written and reviewed by everyone.

The Wider Family

  • Pandoc Markdown — the academic powerhouse: citations, math, definition lists, attribute blocks, and conversion to LaTeX, DOCX, and beyond.
  • Djot — MacFarlane's post-CommonMark experiment that removes Markdown's parsing warts (no lazy continuation, no significant indentation ambiguity); worth watching, not yet mainstream.
  • markdown-it, remark, goldmark, comrak — the parser layer. remark exposes the document as an AST with a plugin pipeline (this is what MDX and most React doc frameworks build on); goldmark powers Hugo; comrak is the Rust GFM implementation.

Security Note

Markdown's raw-HTML passthrough means user-submitted Markdown is an XSS vector by default. Rendering pipelines for untrusted input need sanitization after rendering — rehype-sanitize or DOMPurify on the HTML output — not regex filtering of the Markdown source, which is reliably bypassable.

Choosing

  • READMEs, wikis, team docs: GFM
  • Interactive documentation sites: MDX (Docusaurus, Astro, Next.js)
  • Maximum portability across renderers: strict CommonMark
  • Academic or print-bound writing: Pandoc

Front Matter and Math

Two extensions are so common they feel like core Markdown yet belong to no spec. YAML front matter — metadata between --- fences at the top of a file — is a static-site convention popularized by Jekyll; unless a plugin strips it, a CommonMark parser treats it as a thematic break followed by text. Math is similar: $x^2$ spans and $$...$$ blocks are handled by remark-math, markdown-it-texmath, or platform-side KaTeX/MathJax rendering, each with slightly different delimiter rules around spaces and escaping. Both features silently degrade into visible garbage on renderers without the plugin, so document which extensions your pipeline enables — one line in the repository README prevents most "why is my metadata showing" bug reports.

Preview how your document renders as you write with the Markdown Editor at sdk.is/markdown-editor.