Which Markdown Are You Actually Writing?

Feed a file with a table, a footnote, a task list, and strikethrough into three Markdown readers and only one of them handles all four. We ran the same file through Pandoc, the engine behind FileFlip's converter, three times: once as strict CommonMark, once as GitHub Flavored Markdown, once as Pandoc's own dialect. CommonMark rendered zero of seven extension features correctly. GitHub Flavored Markdown rendered five. Pandoc's dialect, what actually runs behind your conversion, rendered six.

Which Markdown dialect should you write for?

• Write plain CommonMark if the file has to render identically everywhere it goes: no tables, no footnotes, no task lists, nothing outside the base spec.
• Write GitHub Flavored Markdown if the file lives in a README, an issue, or a pull request. It adds tables, strikethrough, task lists, and turns a bare URL into a clickable link.
• Write for Pandoc's dialect if the file is about to get converted, because that is what runs behind Markdown to HTML, Markdown to DOCX, and Markdown to EPUB. Footnotes, definition lists, and citations all survive; a bare URL does not become a link. An EPUB is a zip of web pages covers what that conversion actually builds out of the same Markdown source.

Markdown features at a glance

Every row comes from running pandoc --list-extensions=<format> against markdown, gfm, and commonmark, then confirming the difference by actually converting a file with each one. The three dialects agree on the rest: paragraphs, headings, bold, italic, links, images, and code blocks all come from CommonMark itself, the spec written specifically to give every implementation the same floor.

What actually breaks when you convert a Markdown file?

Whichever feature isn't in the dialect the reader assumes you wrote in. We built one file carrying a pipe table, a footnote, strikethrough, a two-item task list, a bare URL, a definition list, and a smart-quoted phrase, then ran it through Pandoc 3.10.2 three times with -f markdown, -f gfm, and -f commonmark.

The table is the clearest failure. Pipe syntax isn't part of CommonMark at all, so the parser reads | A | B | as ordinary text and folds the whole block, header row, separator, and data, into a single paragraph: | A | B | |---|---| | 1 | 2 |. A task list fares almost as badly. Without the task_lists extension, - [x] Done is just a bullet whose text happens to start with [x], so a checked and an unchecked item render as identical bullets with the brackets left sitting in the text.

GitHub Flavored Markdown renders the table, the footnote, the task list, and the strikethrough, which covers most of what a typical README uses. It misses the two things Pandoc's own dialect adds on top: definition lists and automatic smart-quote conversion. Neither shows up in an ordinary GitHub file, which is why the gap goes unnoticed until you write a glossary.

Does GitHub itself render more than its own spec defines?

Yes, and that gap is exactly where a Pandoc conversion drops formatting without any error.

The formal GFM spec is frozen at version 0.29, dated April 6, 2019, and it defines five extensions over CommonMark: tables, strikethrough, autolinks, task list items, and disallowed raw HTML. GitHub's own website kept adding rendering features after that document stopped moving. Footnote syntax arrived in September 2021, and alert callouts, the > [!NOTE] blocks you see in READMEs, followed later. Neither is in the spec, so anything that implements "GFM" by reading the spec document alone does not have them, even though pandoc --list-extensions=gfm does turn footnotes on.

We tested the two spec-less features against FileFlip's own converter. A > [!NOTE] block runs through as a plain blockquote with the literal text [!NOTE] sitting at the top of it, because Pandoc's markdown reader has no idea it's meant to be a styled callout. :smile: fares the same way, staying as six literal characters instead of becoming 😄.

Where does a converted file lose formatting nobody warned you about?

In your task list checkboxes, once the target is DOCX rather than HTML.

We ran a two-item task list, one item checked and one not, through Markdown to DOCX and unzipped the result. Word's document.xml holds two bullet paragraphs, "Done task" and "Open task", using the identical list style, with no checkbox character anywhere and nothing recording which one was checked. The HTML version keeps that state as a disabled <input type="checkbox"> with a checked attribute; DOCX has no field pandoc can put it in, so it is silently gone. The table, the footnote, and the strikethrough all survive the same conversion intact: w:tbl, a proper word/footnotes.xml entry, and a w:strike run all show up in the file.

Common questions

Will my GitHub README render the same after I convert it?

Mostly. Tables, footnotes, strikethrough, and task lists survive because FileFlip reads far more than raw CommonMark. What breaks: alert callouts fall back to plain blockquotes with the bracket text still visible, emoji shortcodes stay as literal colons and letters, and a bare URL you typed without brackets does not become a clickable link.

Does converting Markdown to DOCX keep my footnotes?

Yes. Pandoc writes them into Word's own footnotes part, word/footnotes.xml, the same mechanism Word's built-in footnote feature uses, so they appear as ordinary Word footnotes rather than inline text.

Why did my checked task boxes disappear in Word?

Because DOCX has nowhere to record checkbox state and Pandoc has no way to invent one. Converting the same file to HTML instead keeps the checked and unchecked state as a real checked attribute; converting it to DOCX collapses both into identical bullet points, covered above.

What's the actual difference between "Markdown" and "GitHub Flavored Markdown"?

GFM is Markdown plus five specific extensions defined in a spec last updated in 2019: tables, strikethrough, autolinks, task list items, and stricter raw HTML handling. Plain "Markdown" has no such spec. John Gruber's original 2004 syntax description never nailed down every edge case, which is the entire reason CommonMark exists: to give every implementation, GitHub's and Pandoc's included, an unambiguous shared core instead of a description everyone reverse-engineered slightly differently.

Convert between them

FileFlip converts Markdown to HTML and Markdown to DOCX in your browser, on a WebAssembly build of Pandoc. The file never leaves your machine, there is no account, and the conversion runs as soon as you drop the file in. Writing GitHub-only syntax like alert callouts or emoji shortcodes into a file you plan to convert is the one habit worth breaking, since neither survives the trip.

For what a conversion generally keeps and drops, see what a conversion actually costs you.

How we measured this

• Tool: Pandoc 3.10.2 on the command line. FileFlip's converter runs pandoc-wasm at Pandoc 3.10, built from the same source, invoked with from: "markdown" and to: "html" or to: "docx" and no extension flags, matching the -f markdown runs here exactly; see src/workers/document.worker.ts and src/utils/convert/document-formats.ts in this repository.
• Extension list: pandoc --list-extensions=markdown, pandoc --list-extensions=gfm, and pandoc --list-extensions=commonmark, which print every extension each format name turns on or off by default.
• Feature test file: one Markdown source containing a strikethrough phrase, a bare URL, a smart-quoted phrase, a two-item task list, a pipe table, a definition list, and a footnote, converted with pandoc -f markdown|gfm|commonmark -t html. A feature counted as correct only when the HTML output matched what that syntax is meant to produce, not merely when it produced no error.
• DOCX test: the same task list, table, footnote, and strikethrough converted with pandoc -f markdown -t docx, then unzipped and inspected directly for w:tbl, w:strike, a populated word/footnotes.xml, and any checkbox marker in word/document.xml.
• Caveat: this is one hand-built test file, not a corpus of real READMEs, so it cannot say how often alert callouts or emoji shortcodes show up in practice, only what happens to them when they do. The 3.10.2 command-line build and the 3.10 WebAssembly build can differ in patch-level bug fixes neither changelog calls out.
• Reproduce it with any Markdown file: pandoc -f markdown -t html yourfile.md matches what FileFlip's converter does; swap -f gfm or -f commonmark to see what a different reader would have done instead.