You paste a table into a Markdown file, it looks perfect on GitHub, and then it shows up as a row of pipes in another app. Nothing is wrong with the file. The two programs implement different versions of Markdown.
Why there are so many flavors
The original Markdown description from 2004 was a prose document with a Perl script. It left many edge cases unspecified, such as how nested lists should be indented or how emphasis next to punctuation should behave. Each implementer made their own choices, and many added features the original lacked, like tables.
The result was dozens of slightly incompatible dialects. A group of implementers published the CommonMark specification, with a thorough test suite, to define the core syntax precisely. It does not add new features; it removes ambiguity in the existing ones.
CommonMark
CommonMark covers headings, emphasis, links, images, lists, block quotes, code blocks and spans, horizontal rules and raw HTML. If you stay inside CommonMark, your file should render the same in any compliant parser.
CommonMark does not include tables, task lists, strikethrough, footnotes or automatic URL linking.
GitHub Flavored Markdown (GFM)
GFM is a strict superset of CommonMark, specified by GitHub. It adds:
- Tables using pipes and a header separator row
- Task lists with
- [ ]and- [x] - Strikethrough with
~~text~~ - Autolinks, so a bare URL becomes a link
- Some safety filtering of raw HTML on GitHub itself
Because GitHub is so widely used, GFM has become the de facto standard for READMEs and many note tools. Plenty of renderers advertise "GFM support", but check which extensions they enable.
Other common variants
- MultiMarkdown adds footnotes, citations and metadata.
- Markdown Extra / PHP Markdown Extra adds definition lists, footnotes and attribute blocks.
- Pandoc Markdown supports a very rich set of extensions, including footnotes, citations and math, and many can be turned on or off individually.
- MDX mixes Markdown with JSX components for web development.
- Platform-specific dialects exist in chat apps, forums and wikis, each supporting a subset and sometimes their own additions such as mentions or spoiler tags.
Where files break between flavors
The usual breakages are predictable:
- Tables appear as plain text with pipes in a CommonMark-only renderer.
- Task lists show literal
[ ]brackets. - Footnotes such as
[^1]appear verbatim unless the renderer supports them. - Line breaks differ: some chat tools turn every newline into a line break, while CommonMark treats a single newline as a space.
- Nested list indentation varies between parsers, especially for ordered lists inside bullets.
- Raw HTML is stripped or escaped by some platforms for security.
Writing portable Markdown
If a file has to survive several tools:
- Stick to CommonMark elements where possible.
- Use tables and task lists only when you know the destination supports GFM.
- Indent nested lists consistently, with four spaces being the safest choice.
- Use blank lines around lists, code blocks and tables.
- Avoid raw HTML unless you can test the destination.
- Preview in the tool the file will actually be used in.
How Docento renders Markdown
Docento's Text & Markdown Editor and the mobile app render GFM, so tables, task lists and strikethrough display as expected. Raw HTML in a file is sanitised on the web editor, so scripts and event handlers are removed. The flavor you write against is worth confirming in whichever tool consumes the file.
Takeaway
Markdown is a family of dialects with a shared core. Treat CommonMark as the common ground, GFM as the likely extension, and always preview in the tool your readers will use.
