Did You Know Markdown Has “Dialects”? CommonMark, GFM, and How They Differ

“Markdown” Isn’t One Thing

Tables look great on GitHub, but paste them into another tool and you get a column of pipes. Bold works in your notes app, but on your blog the ** shows up literally—.

The cause usually isn’t your writing—it’s that Markdown itself isn’t a single standard.

In fact, Markdown has multiple “dialects” (also called flavors), and each platform or tool may use a different one. This article explains why dialects appeared, what the major ones are, and how to work with them.

Why Dialects Appeared

Markdown was created in 2004 by John Gruber as a “lightweight markup language that’s easy to read and write.” But the original Markdown had a big weakness: the spec was ambiguous.

For example, there were no precise rules for “what happens when you nest a list inside a list” or “how to interpret nested emphasis markers.” And Markdown has no concept of “syntax errors”—any input produces some output.

So implementers moved ahead with their own interpretations, and over more than a decade, behavior diverged by implementation. “A document that renders correctly in one system looks different in another” became normal.

That’s how Markdown dialects were born.

Major Markdown Dialects

CommonMark: A “Common Language” Aiming for Standardization

To unify fragmented Markdown, the CommonMark project was launched. It redefined the fuzzy grammar with rigorous rules and a large test suite.

CommonMark’s hallmark is deliberately not adding features. It only specifies basics—headings, paragraphs, lists, links, images, emphasis, code, blockquotes—and instead nails edge-case interpretation. It’s Markdown’s common tongue, prioritizing “the same result from any parser.”

GFM (GitHub Flavored Markdown): The De Facto Standard

GFM is GitHub’s dialect, positioned as a “strict superset” of CommonMark. It keeps CommonMark’s rules and adds extensions like:

Surprisingly, tables are not in CommonMark—they’re a GFM extension. The idea that “Markdown means you can write tables” spread because GFM became ubiquitous.

With GitHub’s influence, GFM is now the de facto standard on many services.

GitHub-Only Extensions: Beyond GFM

Confusingly, not everything on GitHub.com is GFM. Alerts ([!NOTE]), Mermaid diagrams, emoji shortcodes (:smile:), and @mentions are GitHub.com-specific layers, not GFM. They generally won’t work outside GitHub.

Other Notable Dialects

• Pandoc Markdown: For the Pandoc document converter—rich academic features like footnotes, citations, definition lists
• MultiMarkdown: Early extension with metadata and footnotes
• Markdown Extra: PHP-oriented extension
• Goldmark: Go parser used by static site generator Hugo; CommonMark-compliant

Where Dialect Differences Show Up

Difference 1: Available Features Differ

The most obvious gap. A table written in GFM renders as plain text in a CommonMark-only parser. Strikethrough ~~ behaves the same way.

Difference 2: Same Syntax, Different Interpretation

More troublesome: even under the same spec, implementations may differ on details—whether a space is required after # in headings, whether line breaks become <br>, and so on.

Difference 3: Spec-Compliant but Counterintuitive

One trap for Japanese users: in CommonMark-compliant environments, this may not render bold:

**バッチ処理(Message Batches API)**を使用する

It’s not a bug—it’s CommonMark’s “flanking rules” for emphasis. A closing ** after ) isn’t recognized as ending emphasis unless followed by whitespace or punctuation in a specific way. English words are spaced apart, so it’s less common; CJK text runs together and hits this more often.

Fixes: close bold outside the parens (**バッチ処理**(Message Batches API)) or add spaces around the bold. Better CJK handling is an ongoing CommonMark discussion topic.

Which Dialect Major Platforms Use

Watch services like Slack and Discord: “Markdown-flavored but not Markdown.” Slack bold is *single asterisks*, not GFM/CommonMark—writing with the same habits won’t work.

Three Guidelines for Living With Dialects

1. When in Doubt, Stay Within CommonMark

Documents using only basic syntax render almost the same everywhere. If you might migrate platforms later, staying in CommonMark is safest.

2. Know Which Dialect Your Extensions Belong To

When using tables or strikethrough, remember “that’s GFM.” Whether the destination supports GFM tells you if you need rewrites. GitHub-only features (alerts, Mermaid) are even less portable.

3. If Rendering Breaks, Suspect Dialect Mismatch

If you’ve checked your syntax repeatedly and it still breaks, the parser’s dialect may be the issue. Check which spec your platform uses and read that documentation—that’s the fastest path to a fix.

Summary

• Markdown isn’t one standard—multiple dialects (flavors) exist
• Ambiguity in original Markdown led implementations to diverge and dialects to emerge
• CommonMark aims to standardize; GFM extends it as the de facto standard
• Tables and strikethrough are GFM extensions, not “Markdown core”
• Platforms adopt different dialects, so the same syntax can render differently
• For compatibility, writing within CommonMark is safest

Letting go of “Markdown is the same everywhere” makes debugging display issues much easier. Worth checking which dialect your usual platforms speak.