Markdown Extensions: Complete Guide to GFM, Pandoc, MultiMarkdown & CommonMark

What Are Markdown Extensions and Why Do You Need Them?

If you have been writing Markdown for a while, you have probably run into this: a table that renders perfectly on GitHub turns into a mess of pipes and dashes on another platform. What you encountered is the fragmented world of Markdown extensions.

When John Gruber created Markdown in 2004, he defined a fairly minimal set of core syntax — headings, lists, links, images, code, bold, italic, and that is about it. His goal was to make plain text "easy to read and write," not to build a full-featured typesetting system.

But real-world writing demands more than that. You need tables for data, footnotes for citations, task lists for tracking progress, and math formulas for academic notes. None of these are in the original Markdown specification.

So various groups started extending Markdown on their own. GitHub added tables and task lists. Pandoc added footnotes and math. MultiMarkdown added citations and metadata. This created the ecosystem of "Markdown extensions" we see today — diverse, powerful, and honestly, a bit chaotic.

Understanding this history explains a lot of the rendering inconsistencies you might have noticed across platforms. It is usually not that you wrote something wrong — it is that different platforms support different sets of extensions.

The Four Major Markdown Extension Flavors

There are four Markdown variants (also called "flavors") that dominate the extension landscape today.

CommonMark: The Standardized Core, No Extensions

The CommonMark project started in 2014 to resolve ambiguities in the original Markdown specification. According to the CommonMark Spec, CommonMark itself includes no extensions — no tables, no footnotes, no strikethrough.

However, CommonMark parser implementations (such as markdown-it for JavaScript and league/commonmark for PHP) typically provide optional extension mechanisms. You can enable GFM tables, strikethrough, and other features on top of the CommonMark foundation. Think of CommonMark as a standardized foundation, with extensions being floors you add on top.

GFM (GitHub Flavored Markdown): The Most Widely Used Extension Set

GFM is the extension specification defined by GitHub on top of CommonMark. According to GitHub's official documentation, GFM is a strict superset of CommonMark — every valid CommonMark document is valid GFM.

GFM adds exactly four official extensions over CommonMark:

These four extensions were chosen with precision — they cover the features developers use most when writing READMEs and documentation on GitHub. If your content lives primarily on GitHub or GitLab, GFM extensions are likely all you need.

Pandoc Markdown: The Most Extensible Professional Solution

Pandoc is the Swiss Army knife of academic writing and document conversion. It defines its own Markdown dialect with an extensive library of extensions. According to the Pandoc Manual, you can finely control each extension with +extension_name or -extension_name flags.

Some typical Pandoc extension usage:

pandoc -f commonmark+table_captions+footnotes -t html input.md

# Enable YAML metadata block and fenced code blocks
pandoc -f markdown+yaml_metadata_block+fenced_code_blocks -t pdf input.md

Pandoc supports dozens of extensions — footnotes, definition lists, subscript/superscript, math formulas, citations, YAML metadata blocks, fenced divs, inline attributes, and more. It even provides compatibility extensions for MultiMarkdown syntax.

One thing worth noting: Pandoc can operate in multiple Markdown modes (markdown, commonmark, gfm, commonmark_x), and the available extension set varies slightly between modes. Check the "Non-default extensions" chapter in the Pandoc manual for specifics.

MultiMarkdown: The Academic Writing Pioneer

MultiMarkdown, created by Fletcher Penney, was one of the earliest efforts to significantly extend Markdown, primarily for academic and technical documents. It added footnotes, tables, citations, metadata, cross-references, and other publishing-oriented features.

MultiMarkdown has its own parser and is not based on CommonMark. Its syntax rules overlap with but differ from GFM and Pandoc. Today, MultiMarkdown's usage is relatively niche — most of its features can be replicated through Pandoc's compatibility extensions. Unless you have legacy MultiMarkdown documents, Pandoc is generally the recommended alternative.

PHP Markdown Extra: An Important Legacy

Beyond the four major flavors, there is another name worth knowing: PHP Markdown Extra. Created by Michel Fortin as an extension to the PHP Markdown library, it introduced tables, definition lists, footnotes, abbreviations, and fenced code blocks.

While PHP Markdown Extra's influence has waned, many of its syntax designs have been adopted by other parsers. For example, markdown-it's markdown-it-deflist plugin uses a similar definition list syntax. When people talk about "markdown extra," they are generally referring to this lineage of extensions.

Extension Feature Comparison Across Flavors

This table is compiled from Markdown Guide, the Pandoc Manual, and GitHub Docs:

The pattern is clear: GFM has narrow but universally supported coverage; Pandoc has the widest coverage but requires configuration. The more complex your formatting needs, the more likely you are to need Pandoc.

Real-World Platform Compatibility Testing

Specification documents only tell part of the story. I tested several common extension features on mainstream platforms to see what actually works.

GitHub / GitLab

Both GitHub and GitLab support GFM, so tables, strikethrough, task lists, and autolinks all work. However, GitHub's Markdown renderer does not support footnotes — writing [^1] in a GitHub README will display it as plain text, not a footnote link. This catches many people off guard when transitioning from academic writing to GitHub.

GitLab goes further than GitHub, supporting footnotes and math formulas (via KaTeX).

VS Code (Built-in Preview + Markdown Preview Enhanced)

VS Code's built-in Markdown preview supports GFM extensions. Installing the "Markdown Preview Enhanced" extension adds support for footnotes, math formulas (KaTeX/MathJax), Mermaid diagrams, table of contents, and more.

If you write Markdown in VS Code, installing Markdown Preview Enhanced will save you a lot of hassle.

Typora

Typora has impressively comprehensive extension support — tables, footnotes, math formulas, subscript/superscript, highlighting, and table of contents all work out of the box. It essentially bundles GFM extensions with the most common Pandoc extensions. If you want a desktop editor that supports the most extensions without configuration, Typora is a solid choice.

Static Site Generators (Hugo / Jekyll)

Hugo defaults to GFM support and offers various extension options through the Goldmark parser. Jekyll uses kramdown by default, which supports tables, footnotes, and definition lists. Both allow enabling or disabling specific extensions through configuration files.

I once spent half a day debugging why math formulas inside fenced code blocks would not render in Hugo, only to discover that Goldmark's math extension was not explicitly enabled in hugo.toml. This "disabled by default" design is common in static site tools — when a feature does not work, check your configuration first.

How to Choose the Right Markdown Flavor

Your choice depends on your use case:

Writing GitHub READMEs or project documentation→ Use GFM. GitHub only supports GFM extensions, so Pandoc footnotes will not render. Focus on tables, task lists, and code blocks.

Writing blogs or personal notes→ Typora or VS Code + Markdown Preview Enhanced. Their extension support is comprehensive and mostly works out of the box. If your blog uses Hugo or Jekyll, check the build tool's documentation to confirm which extensions are supported.

Writing academic papers or technical books→ Pandoc is the way to go. Its footnotes, citations, math formulas, YAML metadata, and cross-references are unmatched by other flavors. Combined with LaTeX templates, it produces high-quality PDFs.

Maximum compatibility (multi-platform publishing)→ Stick with CommonMark core + GFM extensions. This combination renders correctly on virtually every platform. Avoid footnotes, definition lists, subscript/superscript, and other "advanced" extensions, or prepare multiple versions of your documents.

FAQ

What is the relationship between CommonMark and GFM?

GFM is a strict superset of CommonMark. Think of CommonMark as the foundation and GFM as four rooms built on top (tables, strikethrough, autolinks, task lists). Every valid CommonMark document is valid GFM, but not vice versa.

Will Markdown extension syntax continue to fragment?

This has been debated in the CommonMark community for years. Full unification under a single standard is unlikely — the needs of different use cases are too diverse. A more realistic path: CommonMark remains the stable core, and variants extend it as needed. GitHub's formal specification of GFM is a positive step — at least the most commonly used extensions now have clear definitions.

Pandoc has so many extensions — where do I start?

Do not try to learn them all at once. My recommendation is to start with three:

1. yaml_metadata_block — manage document metadata with YAML
2. footnotes — essential for long-form writing
3. fenced_code_blocks — much more convenient than indented code blocks

Look up other extensions in the Pandoc manual when you encounter specific needs.

Can I use footnotes on GitHub?

No. As of 2026, GitHub's Markdown renderer does not support footnote syntax. If you need annotations in GitHub documents, use HTML hyperlinks to jump to a manual "Notes" section at the bottom, or use <sup> tags for superscript markers.

What is the difference between markdown-it, marked, and showdown?

They are all JavaScript Markdown parsers, differing in how they handle extensions:

• markdown-it — strictly follows CommonMark spec, adds extensions via plugins, most modular design
• marked — fastest parser, supports GFM by default, but less flexible extension mechanism
• showdown — also supports GFM, better suited for browser-side use

If you are building a web application that needs Markdown parsing, markdown-it has the richest plugin ecosystem of the three.

References:

• CommonMark Spec — Official CommonMark specification
• GitHub Docs - Writing on GitHub — Official GitHub GFM documentation
• Pandoc Manual - Non-default Extensions — Complete Pandoc extension list
• Markdown Guide - Extended Syntax — Community reference for Markdown extensions
• Wikipedia - Markdown — Markdown history and flavor background