Web & APIs · 4 min read
Markdown Flavours: CommonMark vs GitHub Flavored Markdown
The same Markdown file can look different on GitHub, in your editor, and in your static site generator. That is because "Markdown" is really a family of dialects built on a loose original description.
Try it yourself with the related tool.
Preview Markdown →Advertisement
Why flavours exist
John Gruber's original 2004 Markdown left many edge cases undefined — how lists nest, how blank lines inside them behave, what happens with underscores inside words. Each implementation made its own choices, so the same text rendered differently from tool to tool.
CommonMark
CommonMark is a precise specification with hundreds of test cases that settles those ambiguities. Most modern renderers follow it, so the basics — headings, emphasis, lists, links, code blocks — now behave consistently almost everywhere.
What GitHub adds
GitHub Flavored Markdown (GFM) is CommonMark plus extensions: tables, task lists with - [ ], ~~strikethrough~~, automatic links for bare URLs, and footnotes. GitHub itself also renders alert blocks such as > [!NOTE], Mermaid diagrams in mermaid code fences, and maths between dollar signs.
Writing portable Markdown
Leave a blank line before and after headings, lists, and code blocks. Use fenced code blocks with a language name rather than indented ones. Prefer * or - consistently for lists, and keep raw HTML to a minimum — some platforms strip it. Preview in the same flavour your readers will see.