Skip to content
All posts
6 min read
markdown
footnotes
gfm
citations
guide

Markdown Footnotes: Complete GFM Syntax Guide (2026)

How to write Markdown footnotes on GitHub, GitLab, and Obsidian — reference syntax, multi-paragraph notes, citations, export quirks, and tools to validate footnote pairs.

Footnotes let you add citations, digressions, and source links without cluttering the main paragraph. GitHub added GFM footnote support in 2021 — and since then, footnotes have spread to GitLab, Obsidian, Hugo, Docusaurus, and most modern static site generators.

They are not part of CommonMark. Use footnotes in a README and they render beautifully on GitHub; paste the same file into Stack Overflow or Slack and readers see raw [^1] markers.

This guide covers GFM footnote syntax, multi-paragraph notes, naming conventions, platform support, export behavior, and how to avoid the mistakes that break rendering.

Basic footnote syntax

Footnotes have two parts: an in-text reference and a definition at document level.

Markdown was created in 2004.[^1]

[^1]: John Gruber and Aaron Swartz designed Markdown for readable plain text.

Rendered output:

  • In-text: a superscript link 1 next to "2004."
  • Bottom: a footnotes section with the definition and a back-link.

Reference markers

Numeric:    [^1] [^2] [^3]
Named:      [^gruber] [^spec] [^license]

Identifiers can be words or numbers. No spaces inside brackets. Case-sensitive in some renderers — pick one style per document.

Definition format

[^identifier]: Footnote text starts here.

Critical: there must be a space after the colon. [^1]:Text may fail; [^1]: Text works.

Definitions can appear anywhere in the document — renderers collect them to the bottom. Convention: place all definitions after the main body, before appendices.

Multiple footnotes in one document

GFM extends CommonMark with tables and task lists.[^gfm]
CommonMark was standardized in 2014.[^cm]
GitHub renders both in README files.[^gh]

[^gfm]: GitHub Flavored Markdown specification.
[^cm]: CommonMark spec at spec.commonmark.org.
[^gh]: See github.github.com/gfm for the full extension list.

Ordering: footnotes typically appear in first-reference order, not definition order. Do not renumber manually — let the renderer handle it.

Multi-paragraph footnotes

Add subsequent paragraphs by indenting with four spaces:

[^long]: First paragraph of the footnote.

    Second paragraph continues the same footnote.
    Still part of [^long] because of indentation.

    Third paragraph if needed.

Alternative in some Pandoc workflows: blank line + four-space indent per paragraph.

GitHub GFM supports multi-paragraph footnotes with indentation. Test in the editor preview before publishing.

Footnotes with formatting inside

Footnote bodies support full inline Markdown:

See the [GFM spec](https://github.github.com/gfm) for details.[^spec]

[^spec]: The spec covers **footnotes**, `code`, and [links](https://example.com).

You can include code spans, bold, italic, and links inside definitions. Block-level elements (fenced code, nested lists) have limited support — keep footnotes concise.

Footnotes vs. other reference patterns

PatternSyntaxBest for
GFM footnote[^1]Academic tone, GitHub docs
Inline link[text](url)Web-native references
Reference-style link[text][ref] + [ref]: urlRepeated URLs
Endnotes (manual)**Notes:** sectionEmail / plain text
HTML <sup><sup>[1]</sup>Non-Markdown pipelines

Footnotes win when the reference is optional reading — the main text flows without clicking, but sources remain one click away.

Platform support (2026)

PlatformFootnotesMulti-paragraphNotes
GitHub / GFM✅✅Since 2021
GitLab GLFM✅✅Inline footnotes also supported
Obsidian✅✅Renders with back-links
Hugo (Goldmark)✅✅Enable in config
Docusaurus✅✅Via MDX/remark
VS Code preview⚠️⚠️Needs extension
Reddit❌❌Use ^superscript instead
Slack❌❌No equivalent
Discord❌❌No equivalent
Stack Overflow❌❌CommonMark subset
CommonMark strict❌❌Extension only

For cross-platform content, footnotes are safe on GitHub + docs sites; avoid them in chat and forums.

Footnotes in READMEs and API docs

README footnotes for license clarifications:

## License

MIT — see [LICENSE](./LICENSE).[^mit]

[^mit]: Includes submodules under `packages/` unless noted otherwise in each package README.

API documentation citing RFCs:

Rate limits follow a token-bucket model.[^rfc]

[^rfc]: Similar to concepts described in RFC 6585 (HTTP 429).

Keep footnotes short in READMEs — readers skim. Move long citations to docs/ pages.

Footnotes and PDF / Word export

Renderers may show footnotes correctly in preview but export differently:

Export targetTypical behavior
Print / PDFEndnotes or bottom-of-page footnotes
DOCXNative Word footnotes or flat text
HTMLLinked <sup> with footnotes <section>
Plain text[^1] markers remain literal

Before publishing a paper, export once and verify. The Markdown to PDF guide covers print workflows.

Pandoc footnotes (different syntax)

Pandoc supports inline footnotes not available in GFM:

Export before sending.^[This is an inline footnote.]

GFM does not support ^[inline] syntax. If your pipeline uses Pandoc and GitHub, stick to reference-style [^id] only.

Validation and tooling

Common errors

ErrorSymptomFix
Missing space after colonRaw [^1]:textAdd space: [^1]: text
Undefined referenceBroken linkAdd matching [^id]: definition
Typo in identifier[^1] vs [^01]Match exactly
Inside code blockLiteral [^1]Move reference outside fence
Nested footnotesUndefined behaviorAvoid

Tools

Footnotes vs. GitLab inline footnotes

GitLab GLFM adds inline footnotes beyond GFM:

Text with an inline note.^[Inline footnote content here.]

This syntax does not render on GitHub. For repos mirrored to both platforms, use reference-style [^id] only.

See the GitLab Markdown guide for GLFM-specific features.

Accessibility

Footnotes improve readability for sighted users but need care for screen readers:

  • Ensure footnote back-links exist (GFM adds these automatically).
  • Do not put critical information only in footnotes — include a summary in the main text.
  • Use descriptive identifiers in named footnotes for debugging ([^mit-license] not [^x]).

Citations and academic writing

GFM footnotes are not BibTeX — for formal academic work, use Pandoc with citeproc or a reference manager export. For technical blog posts and READMEs, GFM footnotes are sufficient:

The algorithm runs in O(n log n).[^knuth]

[^knuth]: Knuth, *The Art of Computer Programming*, Vol. 3 — sorting comparison model.

Link to DOI or arXiv in the footnote body for verifiability.

Quick reference

FormExample
In-text referenceSentence with a footnote.[^1]
Named referenceNamed refs work too.[^source]
Definition[^1]: Footnote content here.
Multi-paragraph[^id]: First paragraph. then indent next lines four spaces

Footnotes are a GFM power feature — use them for citations and asides, validate pairs before merge, and know they will not survive a paste into Slack. For everything else, they make technical writing cleaner.

Written by Markdown Viewer Team. Found this useful? Try the editor →

Keep reading

Hand-picked articles related to this one.