Markdown Extensions: GFM, MDX, and Beyond

Markdown is deceptively simple. David Gruber's original spec is about 20 kilobytes. But the real world has demands: you need tables, you need syntax-highlighted code blocks, you need a way to embed interactive components. Enter markdown extensions.

Today there are dozens of markdown "flavors"—slight variations that add features. Some are de facto standards (GitHub Flavored Markdown). Some are niche (MultiMarkdown). Some are forward-looking (MDX).

This guide breaks down the major extensions and explains when you'd reach for each.

CommonMark: The Standard

In 2012, Gruber stopped maintaining markdown. Without a spec, implementations diverged. Different tools parsed the same markdown differently. GitHub had one flavor, Reddit another, Stack Overflow yet another.

In 2014, a group (including John MacFarlane) created CommonMark: a formal, rigorous spec for markdown. It defines exactly how parsing should work, with test cases.

CommonMark is:

Unambiguous: The spec is precise. The output is predictable.
Extensible: You can build on CommonMark without breaking it.
Widely supported: Most modern tools implement CommonMark (or at least claim to).

If you're writing markdown and wonder "How will this parse?", CommonMark is the reference. Most markdown you write today is CommonMark, whether you realize it or not.

GitHub Flavored Markdown (GFM)

GitHub built markdown for its own needs, extended it for GitHub's users, and called it GFM. It's what you use on GitHub every day.

GFM adds:

Tables

| Heading 1 | Heading 2 |
|-----------|-----------|
| Cell 1    | Cell 2    |
| Cell 3    | Cell 4    |

Tables are essential for documentation, yet base markdown doesn't include them. GFM does.

Task Lists

- [x] Completed task
- [ ] Not yet done
- [ ] Another task

GitHub renders these as interactive checkboxes. You can click to toggle status. Invaluable for bug reports, project tracking, and personal task lists.

Strikethrough

~~This is struck through~~

Useful for corrections without deletion.

Autolinks

Visit https://example.com for more info.

Plain URLs are auto-linked. No need to wrap in brackets.

Mentions and References

@username mentions someone
#123 references an issue

GitHub treats these specially, linking to the user or issue.

Raw HTML

GFM allows inline HTML:

<div class="warning">
This is a warning.
</div>

Useful but potentially dangerous (XSS risk). GitHub allows it in safe contexts.

Where you'd use GFM: Any markdown on GitHub, in documentation that GFM tools will process, in blogs that use GitHub as a backend. For more on markdown tables, see Markdown Tables: Syntax and Best Practices.

MultiMarkdown

MultiMarkdown (MMD) adds:

Metadata blocks (frontmatter)
Cross-references ([Figure 1] links to a figure)
Footnotes ([^1] with definitions)
Definition lists
Math (LaTeX)

Example:

---
author: Ryan McDonald
date: 2026-02-25
---

# Document Title

Here's a footnote[^1].

[^1]: The footnote content.

[Figure 1]: A figure caption

See [Figure 1] for details.

Where you'd use MMD: Academic writing, technical papers, long-form documents that need footnotes and cross-references. Not widely used on the web, but excellent for books and theses.

Org Mode Markup

Emacs users swear by Org Mode. It's more than markdown—it's a markup language with code execution, agenda scheduling, and literate programming.

* Heading 1
** Subheading
   - List item

#+begin_src python
def hello():
    print("Hello, world!")
#+end_src

#+RESULTS:
: Hello, world!

Where you'd use Org Mode: Inside Emacs, academic and research workflows, personal knowledge management, literate programming. Not for web content.

MDX: Markdown + JSX

MDX embeds React components directly in markdown:

# Welcome

<Button onClick={() => alert('Clicked!')}>
  Click me
</Button>

Or use components in markdown syntax:

<Video src="intro.mp4" />

MDX is powerful because it combines:

Markdown's readability: Still easy to scan and write
React's interactivity: Add buttons, forms, animations
Code execution: Run JavaScript at build time

This blog post you're reading? It's likely MDX (or a similar format). Next.js, Docusaurus, and many modern doc sites use MDX.

Example use:

export const Button = ({ children }) => (
  <button className="px-4 py-2 bg-blue-500 text-white rounded">
    {children}
  </button>
)

# Interactive Guide

Click the button to see what happens:

<Button>Try me</Button>

Where you'd use MDX: Modern web content, technical blogs, interactive documentation, websites built with React or Next.js. Not suitable for contexts where you need portable markdown (like git repos or legacy systems).

AsciiDoc

AsciiDoc is more like DocBook's simpler cousin. It's a lightweight markup language with more features than markdown:

= Document Title
Author Name
v1.0, 2026-02-25

== Section

This is a paragraph.

[NOTE]
====
This is a note.
====

[source,python]
----
def hello():
    print("Hello")
----

AsciiDoc supports admonitions, includes, and complex document structures natively.

Where you'd use AsciiDoc: Large technical documentation projects (especially Java/Open Source projects), books, long-form technical content that needs more structure than markdown provides.

Comparison Table

Feature	CommonMark	GFM	MMD	MDX	AsciiDoc
Tables	No	Yes	Yes	Yes	Yes
Footnotes	No	No	Yes	Yes	Yes
Components/Includes	No	No	Limited	Yes	Yes
Task lists	No	Yes	No	Yes	No
Admonitions	No	Limited	No	Yes	Yes
Math/LaTeX	No	No	Yes	Yes	Limited
Learning curve	15 min	20 min	30 min	Weeks	45 min
Portability	Excellent	Good	OK	Poor	OK
Web friendliness	Good	Excellent	OK	Excellent	OK
Code interactivity	No	No	No	Yes	Limited

Choosing the Right Format

Use CommonMark if...

You want maximum compatibility
You're writing something that might outlive the current tooling
You need portability

Use GFM if...

You're writing on GitHub, GitLab, or Bitbucket
You need tables and task lists
You're documenting for developers

Use MDX if...

You're building a Next.js or React site
You need interactive components
You're willing to trade portability for interactivity

Use MultiMarkdown if...

You're writing academic or long-form content
You need footnotes, cross-references, and math
You're targeting PDF output

Use AsciiDoc if...

You're writing a large, complex document
You need robust structure and includes
You're in a Java/Open Source community

Use Org Mode if...

You're an Emacs user
You need literate programming features
You want to manage a personal knowledge base

A Practical Example: Building a Blog

Let's say you're building a technical blog. Which format?

Answer: MDX (or Markdown + a tool like Next.js that handles conversion)

Why? You want:

Readable source files (markdown)
Syntax-highlighted code blocks (GFM provides this)
Embedded components (video, callouts, interactive demos)
Web-friendly output

Start with GFM (tables, code blocks, task lists), add React components as needed (MDX), and you have a powerful blogging platform.

Future of Markdown

Markdown is fragmenting. That's both good and bad.

Good: Extensions let you handle real-world needs (tables, components, footnotes).

Bad: There's no single "markdown" anymore. When someone says "markdown," you need to ask "which kind?"

The CommonMark spec is stable. But practical markdown (on GitHub, in blogs, in docs) continues to evolve. The lesson: understand the format you're using, and be explicit when sharing with others.

Getting Started

If you're new to markdown, start with CommonMark basics (headings, lists, emphasis, links, code blocks).
If you're on GitHub, learn GFM (especially tables and task lists).
If you're building interactive content, explore MDX.
For academic or long-form work, consider MultiMarkdown.
For everything else, GFM is your friend.

Most of your markdown life will be CommonMark + GFM. That's enough for nearly everything.

For more markdown essentials, see Why Markdown is the Standard for Software Documentation and Markdown in Technical Writing Workflows.

Download OpenMark to read and edit markdown in all these flavors with beautiful rendering. $9.99, one-time purchase.