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
1next 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
| Pattern | Syntax | Best for |
|---|---|---|
| GFM footnote | [^1] | Academic tone, GitHub docs |
| Inline link | [text](url) | Web-native references |
| Reference-style link | [text][ref] + [ref]: url | Repeated URLs |
| Endnotes (manual) | **Notes:** section | Email / 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)
| Platform | Footnotes | Multi-paragraph | Notes |
|---|---|---|---|
| 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 |
| ❌ | ❌ | 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 target | Typical behavior |
|---|---|
| Print / PDF | Endnotes or bottom-of-page footnotes |
| DOCX | Native Word footnotes or flat text |
| HTML | Linked <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
| Error | Symptom | Fix |
|---|---|---|
| Missing space after colon | Raw [^1]:text | Add space: [^1]: text |
| Undefined reference | Broken link | Add matching [^id]: definition |
| Typo in identifier | [^1] vs [^01] | Match exactly |
| Inside code block | Literal [^1] | Move reference outside fence |
| Nested footnotes | Undefined behavior | Avoid |
Tools
- Footnote helper — compose and validate pairs
- GFM checklist — catch table/list issues nearby
- Editor preview — see rendered footnotes live
- Validate API — CI gate on docs repo
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.
Related articles
- CommonMark vs GFM — when footnotes are supported
- Markdown links guide — reference-style links
- GitHub README guide — footnotes in READMEs
- Docs-as-code guide — CI validation
- Obsidian Markdown guide — footnotes in vaults
Quick reference
| Form | Example |
|---|---|
| In-text reference | Sentence with a footnote.[^1] |
| Named reference | Named 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.
CommonMark and GitHub Flavored Markdown explained — syntax differences, portability matrix, platform support tables, and a decision framework for READMEs, docs, chat, and AI pipelines.
The in-depth GitHub README playbook — star-winning structure, GFM tables and alerts, Mermaid diagrams, profile READMEs, badges, CI snippets, anti-patterns, and a copy-paste template.
A power-user tutorial for advanced Markdown tasks — diffing revisions, validating Mermaid, redacting secrets, normalizing structure, merging and splitting docs, and managing footnotes.