Markdown Footnotes: GFM vs. Pandoc Syntax Compared

Quick answer

Both GFM and Pandoc write a footnote the same basic way: a [^1] reference where the note belongs, and a [^1]: content definition somewhere else in the document. Wherever the definition sits, the rendered footnote collects at the bottom of the page. That's the entire shared core of markdown footnotes syntax. Everything past it is where the two flavors disagree — Pandoc adds true inline footnotes, lets a footnote span multiple paragraphs, and restricts where a definition can legally sit. GFM keeps things simpler and more permissive about placement, but can't do either of those two things.

How it actually works

Why footnotes aren't part of core CommonMark

Footnotes were left out of CommonMark on purpose, not by oversight. Pandoc's block-style footnote definition — [^1]: ... sitting on its own line — structurally collides with CommonMark's link reference definition syntax, and a parser can't always tell the two apart without extra rules. That ambiguity is why footnotes stayed an extension instead of becoming a spec feature. It's also why implementations forked: GitHub's own cmark fork ended up adopting Kramdown-style footnotes rather than porting Pandoc's syntax outright. Same underlying story as why the same file can render differently across parsers — an unspecified feature means every renderer gets to decide for itself.

GFM footnote syntax

GitHub Flavored Markdown uses [^1] for the reference and [^1]: My reference. for the definition, and it's newer than most people assume. GitHub shipped footnote support platform-wide on September 30, 2021, available in issues, pull requests, discussions, and README files. Need more than one line in a footnote? Add two trailing spaces at the end of a line inside the definition to force a break — that's a forced line break, not a real multi-paragraph footnote. Worth knowing: footnotes render fine in most GFM contexts but aren't supported in GitHub wikis at all. If you're comparing extensions GitHub has bolted onto plain Markdown, footnotes sit alongside GFM's autolinks as another case of the platform extending the spec on its own terms.

Pandoc footnote syntax

Pandoc's Markdown uses the identical [^identifier] reference and [^identifier]: content definition pattern, gated behind the footnotes extension flag, so the overlap with GFM is real, not coincidental. Past that shared core, Pandoc goes further in two ways GFM doesn't match. First, inline footnotes: ^[content] drops a note directly at the point of use with no separate identifier to manage, though an inline note can't hold more than one paragraph. Second, full multi-paragraph footnotes — indent a continuation paragraph the way you'd indent content under a list item, and it becomes part of the same footnote. Pandoc also enforces a placement rule GFM doesn't document: a footnote definition can't sit inside a list, block quote, or table. Moving content between the two — say, converting a document with Pandoc — that restriction is the detail most likely to trip up a straight copy-paste.

When to use it (and when to skip it)

Reach for reference-style [^1] footnotes when you're citing a source, adding an aside that would otherwise interrupt a sentence, or writing for a renderer you've already confirmed handles the syntax. Maintaining a long document? Use named labels instead of numbers — [^export] instead of [^1] — so you don't have to renumber anything by hand when a footnote gets added or removed. The rendered numbering adjusts on its own.

Skip footnotes when you don't control the renderer and portability matters more than the citation format. A parenthetical note or a linked reference list degrades more gracefully across tools that have never heard of [^1] syntax at all.

The most common trap sits at the intersection of both flavors: writing [^1]: content indented directly under a bullet point. It renders in some tools, but breaks under Pandoc's stricter parser, since Pandoc won't accept a footnote definition nested inside a list block. The safer pattern — and the one that survives a switch between renderers — is keeping every footnote definition at the top level of the document, outside any list, quote, or table. Same caution worth applying to other Markdown extras most editors skip.

Frequently Asked Questions

Do GFM and Pandoc use the same footnote syntax?

They share the same basic pattern — a [^1] reference in the text and a [^1]: content definition — but Pandoc adds capabilities GFM doesn't have: true inline footnotes with ^[content], full multi-paragraph footnote bodies via indentation, and a rule that footnote definitions can't sit inside a list, block quote, or table. GFM's version is simpler and more permissive about placement, but can't do inline notes or multi-paragraph footnotes.

Why aren't footnotes part of standard Markdown?

Footnotes were never included in core CommonMark. Pandoc's block-style footnote definition syntax structurally conflicts with CommonMark's link reference definition grammar, so there's no clean way to add it without breaking something else. Each flavor — GitHub, Pandoc, Kramdown — built its own extension instead, which is why the syntax mostly overlaps but the edge cases don't.

Can I write a footnote inside a bullet list?

Be careful — this is the most common portability trap. Indenting a [^1]: content line directly under a list item works in some renderers but breaks under Pandoc's stricter parser, since Pandoc doesn't allow footnote definitions inside list blocks. The safer pattern is to place the definition at the top level of the document, outside any nested list, quote, or table.

How Carets fits in

Whichever syntax you're writing footnotes in, the file underneath is still plain Markdown — and that's exactly what Carets is built to hold. Carets keeps notes, research, and citations as plain text, organized into files, projects, and tags, so a footnoted draft stays portable instead of getting locked into one renderer's interpretation of [^1].

Carets is native and fast on iPhone, iPad, and Mac, which matters when you're checking how a footnote actually renders instead of guessing. And because everything stays plain text, a document with footnotes written today opens the same way next year, regardless of which Markdown flavor eventually becomes the one you're publishing through.

Carets is a fast, native notes and code editor for iPhone, iPad, and Mac — Markdown, plain text, and code with syntax highlighting, organized into files, projects, and tags. Get Carets on the App Store for iPhone, iPad, and Mac.