If you have ever written a README.md, dropped a # in front of a heading, or wrapped a word in double asterisks to make it bold, you have used Markdown. It is so embedded in how developers write that it is easy to forget it was invented by one person, solving one problem, just over two decades ago.
But Markdown’s simplicity is also the source of its biggest challenge. Because the original spec left so many things open to interpretation, the community filled in the gaps, and that led to dozens of “flavors” that do not always agree with each other. If you have ever had a document render perfectly on GitHub but break on another platform, you have felt this firsthand.
This post walks through how Markdown started, how it fractured, and how standards like CommonMark are pulling it back together, which matters more than ever as teams collaborate across tools, platforms, and workflows.
How Markdown started
In the early 2000s, writing for the web meant writing HTML by hand. For bloggers and technical writers, that meant wrapping every paragraph in <p> tags, every link in <a href="">, and every heading in <h2>. It worked, but it was tedious and made proofreading painful.
John Gruber, the creator of the tech blog Daring Fireball, felt this friction daily. As he put it, writing in raw HTML “made it hard to proofread my work.” He wanted a way to write content that was readable as plain text and could convert cleanly to HTML when needed.
In 2004, Gruber released Markdown along with a Perl script called Markdown.pl that handled the conversion. Aaron Swartz, the brilliant programmer and digital rights activist, served as a key collaborator, helping shape the syntax and test early implementations. Their stated goal was to let people “write using an easy-to-read and easy-to-write plain text format, optionally convert it to structurally valid XHTML (or HTML).”
The idea was not entirely new. Earlier lightweight markup languages like setext (circa 1992), Textile (2002), and reStructuredText (2002) had explored similar territory. But Markdown hit a sweet spot: its syntax borrowed from conventions people already used in plain text emails, like using asterisks for emphasis and dashes for lists. You did not have to learn Markdown so much as recognize it.
Markdown caught on quickly with bloggers and early web communities. And because Gruber intentionally left curly braces unreserved for future extensions, other developers started building on top of it almost immediately.
The fragmentation problem
Here is where things got complicated.
Gruber’s original Markdown description was deliberately informal. It was a syntax guide, not a formal specification. There was no test suite, no edge-case documentation, and no ruling on how parsers should handle ambiguous input. Markdown.pl itself was last updated on December 17, 2004, and it had known bugs.
As Markdown’s popularity exploded, platforms like GitHub, Reddit, Stack Overflow, and dozens of others adopted it, but each one had to make their own decisions about how to handle the gaps. What happens when you nest a list inside a blockquote? How do you handle blank lines inside a list item? What about tables (which Markdown did not originally support at all)?
The result was a growing ecosystem of Markdown “flavors,” each solving real problems but each doing it slightly differently. A document that rendered perfectly in one tool might break or look wrong in another. And because nothing in Markdown counts as a “syntax error,” these inconsistencies were often invisible until someone moved content between systems.
By 2012, the situation was serious enough that Jeff Atwood (co-founder of Stack Overflow) wrote a public blog post urging Gruber to support a standardization effort. As Atwood put it, the community had been “accidentally fragmenting Markdown while popularizing it.”
The major Markdown flavors
Over the past two decades, several Markdown flavors have become widely adopted. Here is a look at the ones you are most likely to encounter as a developer or technical writer.
CommonMark
CommonMark is the closest thing Markdown has to a formal standard. Launched in 2014 by a group that included John MacFarlane (creator of Pandoc), Jeff Atwood, and contributors from GitHub, GitLab, Reddit, and Stack Exchange, CommonMark provides an unambiguous specification with over 500 conformance tests.
The goal was straightforward: define exactly how every piece of Markdown syntax should behave, eliminate the ambiguities in Gruber’s original description, and give implementers a shared foundation to build on. CommonMark intentionally keeps its scope tight, covering the core syntax that Gruber originally defined, while allowing extensions to be layered on top without breaking the base spec.
Today, CommonMark has been adopted by major platforms including GitHub, GitLab, Reddit, Discourse, Stack Exchange, and Swift. It has reference implementations in C and JavaScript, and third-party implementations in over a dozen languages.
Why it matters: CommonMark is the baseline. When a tool says it supports “Markdown,” increasingly what it means is CommonMark plus whatever extensions it adds on top.
GitHub Flavored Markdown (GFM)
GitHub started using its own Markdown variant as early as 2009, adding features developers needed that original Markdown lacked. In 2017, GitHub formalized this as GitHub Flavored Markdown (GFM), building it explicitly as a strict superset of CommonMark.
GFM follows the CommonMark specification exactly, then adds four extensions: tables, strikethrough text (~~like this~~), autolinks (URLs that become clickable without explicit link syntax), and task lists (checkboxes with - [ ] and - [x]). It also includes GitHub-specific features like auto-linking to commits, issues, and usernames.
Because GFM is built on CommonMark, any valid CommonMark document renders correctly under GFM. The reverse is not always true, since GFM’s extensions are not part of the CommonMark spec.
Why it matters: GFM is arguably the most widely encountered Markdown flavor in the developer world, given GitHub’s scale. Its decision to base its spec on CommonMark was a significant validation of the standardization effort.
MultiMarkdown (MMD)
Fletcher Penney created MultiMarkdown as an early and ambitious extension of Gruber’s original Markdown. It added features aimed at more complex document types: footnotes, tables, metadata headers, definition lists, math support, and cross-references. MultiMarkdown was designed with academic and long-form writing in mind, supporting export to formats like LaTeX, PDF, and EPUB in addition to HTML.
Why it matters: MultiMarkdown pushed the boundaries of what Markdown could do and influenced many of the extensions that later flavors adopted. However, it is not based on CommonMark and has its own parsing behavior.
Markdown Extra
Michel Fortin created Markdown Extra as a PHP extension to the original Markdown, later ported to Python and Ruby. It added footnotes, abbreviations, definition lists, fenced code blocks, tables, and the ability to use Markdown inside HTML block elements. Markdown Extra is supported in CMS platforms like Drupal, TYPO3, and others.
Why it matters: Markdown Extra introduced several features (especially fenced code blocks and tables) that became so widely expected that they are now considered near-standard across most flavors.
R Markdown
R Markdown integrates Markdown with the R programming language, allowing authors to embed executable R code directly in their documents. When rendered, the code runs and the output (charts, tables, statistical results) is inserted inline. It is widely used in data science, academic research, and reproducible reporting.
Why it matters: R Markdown showed that Markdown could serve as a foundation for computational documents, not just static content.
Pandoc’s Markdown
John MacFarlane’s Pandoc is a universal document converter that supports its own extended Markdown dialect. Pandoc’s Markdown includes footnotes, tables, definition lists, metadata blocks, math, citations, and more. Because Pandoc can convert between dozens of formats (Markdown, HTML, LaTeX, DOCX, PDF, EPUB, and others), its Markdown flavor is one of the most feature-rich available.
Why it matters: Pandoc bridges the gap between Markdown and the wider document ecosystem. If you need Markdown to become a PDF, a Word doc, or a LaTeX paper, Pandoc is usually the tool that gets you there.
Why CommonMark matters now more than ever
The proliferation of flavors is not going away. Different platforms have different needs, and extensions will keep evolving. But the fragmentation problem is real, and it is getting more expensive as teams collaborate across more tools and content flows into more channels (websites, APIs, AI systems, internal knowledge bases).
CommonMark addresses this by providing a reliable, tested foundation. When you write CommonMark-compliant Markdown, you know how it will render. Extensions can add features on top, but the base behavior is predictable. This is why the most significant Markdown platforms (GitHub, GitLab, Reddit, Discourse, Stack Exchange) have converged on CommonMark as their starting point.
For teams working with documentation, the practical benefit is portability. Markdown written in a CommonMark-compliant editor can move to a Git repository, a static site generator, or another tool without unexpected rendering changes. That portability matters whether you are writing internal docs, maintaining a developer portal, or collaborating on a spec with people who use different tools.
How HackMD builds on CommonMark
At HackMD, CommonMark is the foundation of our Markdown editor. Our parser, built on the markdown-it library, provides full CommonMark support with extensions layered on top for the features teams actually need: MathJax for formulas, Mermaid and Graphviz for diagrams, Vega-Lite for data visualizations, and more.
We chose CommonMark deliberately. When your content is built on a well-specified standard, it stays portable. You can write and collaborate in HackMD, then export to GitHub, a static site, or any other system that understands CommonMark, and it renders the way you expect.
But we also think the real value goes beyond spec compliance. Markdown’s original promise was that you could focus on writing instead of formatting. CommonMark delivers on that promise at scale, across teams, tools, and time. And when you add real-time collaboration on top, with comments, shared editing, and version history, Markdown stops being a solo writing format and becomes the way teams think together.
That is what HackMD is built for: a place where the simplicity and portability of Markdown meets the reality of how teams actually work, brainstorming, iterating, and building knowledge together.
Read more: Choosing a CMS for Technical Teams in 2026
Looking ahead
Markdown has come a long way from a Perl script and a blog post in 2004. It is now the default format for README files, developer documentation, note-taking apps, collaborative editing, and increasingly, the structured content that feeds AI systems.
The flavors are not going away, and that is fine. Different contexts will always need different extensions. But the trend toward CommonMark as the shared foundation is clear, and it is making the entire ecosystem more interoperable, more portable, and more reliable.
If you write Markdown, understanding the flavor you are using (and the standard it builds on) is worth your time. And if you are choosing tools for your team, look for CommonMark support as a baseline. Your future self, and everyone you collaborate with, will thank you.
