Markdown Footnotes: Complete Syntax Guide (2026)

TL;DR: Markdown footnotes use [^1] as an inline marker and [^1]: text as the definition. They are a GFM (GitHub Flavored Markdown) extension — not part of the core CommonMark spec. GitHub, GitLab, Obsidian, Pandoc, and MacMD Viewer all render them. VS Code's built-in preview does not. Footnotes are auto-numbered in render order regardless of the label you use.

Footnotes let you add citations, asides, and clarifications without cluttering the body of your document. The syntax looks simple on the surface — a bracketed marker inline, a matching definition below — but the details around naming, multi-paragraph content, and platform support trip up writers who expect footnotes to behave like a core Markdown feature. They are not: footnotes are an extension, and not every renderer supports them.

This guide covers everything you need to know about Markdown footnotes: the exact syntax, named versus numbered labels, multi-paragraph definitions, how footnotes convert to HTML, common mistakes, and which platforms render them correctly. If you are building documentation that also needs links and references, the links in Markdown guide covers hyperlink syntax, and the Markdown text formatting guide explains inline formatting you can use inside footnote definitions.

What Are Markdown Footnotes and Where Do They Come From?

Markdown footnotes are a GFM (GitHub Flavored Markdown) extension that adds academic-style reference notes to Markdown documents. They are not part of the CommonMark specification — the core standard that defines basic Markdown syntax like headings, bold, and lists.

CommonMark intentionally omits footnotes because the spec authors wanted a minimal, unambiguous baseline. Footnote syntax was later added by various extended flavors — most prominently GFM, which GitHub published in 2017. Since then, GitLab, Obsidian, Pandoc, and other tools have adopted compatible footnote syntax, making it a de-facto standard extension even though it remains outside CommonMark proper.

The consequence: your footnotes render perfectly on GitHub, then appear as raw [^1] text when you paste the same Markdown into a CommonMark-strict renderer. Always check platform support before relying on footnotes for important documents.

How Do You Write a Basic Markdown Footnote?

A Markdown footnote has two parts: an inline marker in the body text, and a definition elsewhere in the document. Both parts use the same label inside brackets with a caret (^) prefix.

Inline marker — placed where you want the superscript reference to appear:

The research confirmed the hypothesis.[^1]

Definition — placed anywhere after the body text (typically at the bottom of the document):

[^1]: Smith, J. (2024). *Hypothesis Testing in Practice*. Academic Press.

The rendered output looks like this: a clickable superscript ¹ at the marker location, and a numbered list at the bottom of the page. Clicking the superscript jumps to the footnote; a return arrow at the end of the definition jumps back to the marker location.

Here is a complete example:

Markdown was created by John Gruber in 2004.[^gruber] It was designed to be
readable as plain text while also converting cleanly to HTML.[^design]
 
[^gruber]: Gruber, J. (2004). Markdown. Daring Fireball. https://daringfireball.net/projects/markdown/
[^design]: The original goal was "readability" — the formatted source should
    be publishable as-is without looking like it's been marked up with tags.

The blank line before the definition block is not strictly required by all parsers, but it is a safe habit. Several renderers fail to detect the definition block if it immediately follows body text without a separator.

What Is the Difference Between Named and Numbered Footnotes?

There is no functional difference — named and numbered footnotes behave identically. The label inside the brackets is purely an identifier you use in the source file to match inline markers to their definitions.

Numbered labels:

Climate data shows a clear trend.[^1] Sea levels have risen measurably.[^2]
 
[^1]: IPCC Sixth Assessment Report (2021), Chapter 2.
[^2]: Tide gauge data from NOAA, 1993–2023.

Named labels:

Climate data shows a clear trend.[^ipcc] Sea levels have risen measurably.[^noaa]
 
[^ipcc]: IPCC Sixth Assessment Report (2021), Chapter 2.
[^noaa]: Tide gauge data from NOAA, 1993–2023.

Both examples produce identical rendered output: sequential superscript numbers (1, 2) linked to a footnote list at the bottom. The rendered numbers reflect the order markers appear in the document, not the labels you assigned. If [^noaa] appears before [^ipcc] in the body text, it will render as footnote 1.

Named labels are recommended for longer documents. When you have twenty footnotes, scanning source text for [^42] is harder than scanning for [^ipcc-2021]. Labels can contain letters, numbers, and hyphens — no spaces allowed.

<!-- Valid labels -->
[^1]
[^note]
[^source-2024]
[^ref42]
 
<!-- Invalid — space inside label -->
[^my note]

How Do You Write Multi-Paragraph Markdown Footnotes?

A footnote definition can contain multiple paragraphs, code blocks, and blockquotes. The rule: any continuation content must be indented by four spaces relative to the definition's left margin.

Single paragraph (basic):

[^1]: This is a single-paragraph footnote. It fits on one line.

Multi-paragraph footnote:

[^1]: First paragraph of the footnote. This line starts immediately after the colon.
 
    Second paragraph. Indented by four spaces to stay attached to the footnote.
    The indentation signals to the parser that this content belongs to [^1].
 
    Third paragraph. Same four-space indent.

Without the four-space indentation, the second paragraph breaks out of the footnote block and renders as normal body text — a common silent failure.

Footnote with a code block:

[^cli]: Run the following to verify your installation:
 
    ```bash
    markdown --version

Output should show version 2.x or higher.

**Footnote with a blockquote:**

```markdown
[^source]: The original specification stated:

    > Markdown is intended to be as easy-to-read and easy-to-write as is feasible.

    This principle guided every design decision in the syntax.

The four-space rule applies to all continuation content, not just paragraphs. You can also embed ordered and unordered lists inside a footnote using the same indentation approach.

How Do Markdown Footnotes Convert to HTML?

Understanding the HTML output helps diagnose rendering issues and write cleaner styles. GFM-compatible renderers produce consistent HTML across platforms.

The inline marker [^1] becomes a superscript anchor:

<sup id="fnref:1">
  <a href="#fn:1" class="footnote-ref" role="doc-noteref">1</a>
</sup>

The footnote list renders as an ordered list inside a <section> element (or a <div> on some renderers):

<section class="footnotes" role="doc-endnotes">
  <hr>
  <ol>
    <li id="fn:1">
      <p>Your footnote text here.
        <a href="#fnref:1" class="footnote-backref" role="doc-backlink">↩</a>
      </p>
    </li>
  </ol>
</section>

Key observations from this structure:

• Inline markers use id="fnref:N" and href="#fn:N" — the : separator is part of the standard GFM output
• Definitions use id="fn:N" — the target of the inline link
• The back-arrow (↩) links back to #fnref:N, enabling two-way navigation
• All footnotes collect at the bottom regardless of where you placed definitions in the source

You can inspect this structure directly using the Markdown to HTML converter, which shows the rendered HTML alongside your source Markdown.

What Are the Most Common Markdown Footnote Mistakes?

Four mistakes cause nearly all broken footnote rendering. Each fails silently — the footnote either renders as plain text or disappears entirely.

Mistake 1: Missing colon in the definition

The colon after the label is mandatory. Without it, the line is not recognized as a footnote definition:

<!-- BROKEN — no colon -->
[^1] This is not a footnote definition.
 
<!-- CORRECT -->
[^1]: This is a footnote definition.

Mistake 2: Space before the colon

Unlike some Markdown syntax, a space before the colon in the definition breaks parsing:

<!-- BROKEN — space before colon -->
[^1] : The space here prevents recognition as a definition.
 
<!-- CORRECT — colon immediately after the closing bracket -->
[^1]: No space before the colon.

Mistake 3: Label mismatch between marker and definition

The label in [^label] must exactly match the label in [^label]:. Case sensitivity and character differences both break the link:

<!-- BROKEN — labels don't match -->
The data is compelling.[^Source]
 
[^source]: Smith (2024). Note the lowercase 's' doesn't match 'Source'.
 
<!-- CORRECT — exact match -->
The data is compelling.[^source]
 
[^source]: Smith (2024). Labels match exactly.

Mistake 4: Missing four-space indent in multi-paragraph definitions

This is the most common mistake. Continuation content without proper indentation breaks out of the footnote:

<!-- BROKEN — continuation not indented -->
[^1]: First paragraph of the footnote.
 
Second paragraph — this renders as body text, not part of the footnote.
 
<!-- CORRECT — continuation indented by four spaces -->
[^1]: First paragraph of the footnote.
 
    Second paragraph — indented by four spaces, stays inside the footnote.

The Markdown cheat sheet has a quick-reference section for footnote syntax alongside other commonly confused GFM extensions.

How Are Markdown Footnotes Different from Inline Links?

Footnotes and inline links are both ways to attach supplementary information to text, but they serve different purposes and produce different output.

Use inline links when pointing to a URL the reader might follow immediately. Use footnotes for citations, disclaimers, or clarifications that would interrupt the flow of reading if placed inline. Academic writing, technical documentation, and long-form articles are the primary use cases for footnotes.

Reference-style links (a related but distinct feature) let you define a URL once and reuse it across the document — similar in structure to footnotes but not the same thing. See the links in Markdown guide for the full comparison.

Which Platforms Support Markdown Footnotes?

Support varies significantly by platform because footnotes are a GFM extension, not part of the core CommonMark specification.

The VS Code situation is a common source of confusion. If you write footnotes in VS Code's built-in Cmd+Shift+V preview and they render as raw [^1] text, that is expected — the built-in renderer does not include the GFM footnote extension. The footnotes will still render correctly on GitHub once you push the file.

If you want a native macOS footnote preview without leaving your text editor, MacMD Viewer ($19.99, one-time) renders GFM footnotes — including multi-paragraph definitions and back-navigation arrows — the same way GitHub does. It watches your file for changes, so the preview updates as you write in any editor.

How Do You Use Markdown Footnotes in Practice?

Three patterns cover most real-world footnote use cases.

Citation footnotes (academic / technical writing):

The study found no statistically significant effect.[^chen2023]
 
[^chen2023]: Chen, L., et al. (2023). "Effects of X on Y." *Journal of Z*, 12(4), 45–61.
    https://doi.org/10.xxxx/example

Clarification footnotes (avoiding prose interruptions):

The algorithm runs in O(n log n) time.[^bigO] For most practical inputs,
this means completion in under one second.
 
[^bigO]: O(n log n) is the lower bound for comparison-based sorting algorithms,
    proven by the decision tree model. Radix sort achieves O(n) but requires
    integer keys within a bounded range.

Disclaimer footnotes (legal / compliance documents):

Past performance does not guarantee future results.[^disclaimer]
 
[^disclaimer]: This document is for informational purposes only and does not
    constitute financial advice. Consult a qualified financial advisor before
    making investment decisions.

In all three cases, the footnote moves detail out of the reading flow without removing it from the document. Readers who need the full context can follow the superscript; readers who do not can keep reading without interruption.

For documents that mix footnotes with other reference content, the Markdown cheat sheet provides a single-page reference for all GFM syntax — useful when you need a quick reminder of footnote syntax alongside tables, task lists, and strikethrough.

How Do You Preview Markdown Footnotes on macOS?

macOS does not render Markdown natively. Quick Look displays .md files as plain text, so footnotes appear as raw [^1] markers instead of rendered superscripts.

MacMD Viewer renders GFM footnotes exactly as GitHub does: inline markers become clickable superscripts, definitions collect into a numbered list at the bottom, and back-arrows let readers navigate between the marker and the definition. The app registers as the default handler for .md files, so double-clicking any Markdown file opens a live rendered preview. Download MacMD Viewer ($19.99, one-time purchase — no subscription).

Obsidian renders footnotes correctly in Reading View. If you use Obsidian as a note-taking environment, footnote support is built in.

Pandoc (terminal) converts Markdown with footnotes to HTML or PDF: pandoc input.md -o output.html --from=markdown+footnotes. Pandoc requires the explicit +footnotes flag when the input format is markdown (its strict mode); footnotes are enabled by default with --from=gfm.

The Markdown to HTML converter on this site also renders GFM footnotes — paste your Markdown and check the HTML output to verify your footnote syntax is correct before publishing.

Frequently Asked Questions

How do you add a footnote in Markdown?

Place [^1] in your body text where the superscript should appear. Then add [^1]: Your footnote text anywhere in the document (typically at the bottom). Both labels must match exactly. The rendered output shows a numbered superscript linked to a footnote list.

Are Markdown footnotes supported on GitHub?

Yes. GitHub Flavored Markdown (GFM) fully supports footnotes. The inline marker renders as a clickable superscript and GitHub automatically appends a formatted footnote section at the bottom of the rendered file.

What is the difference between named and numbered Markdown footnotes?

Only the label differs. [^1] and [^note] work identically — the label is just an identifier for matching markers to definitions. All footnotes are numbered sequentially in the order their inline markers appear in the document, regardless of what labels you assigned.

Do Markdown footnotes work in VS Code?

Not in VS Code's built-in preview. The standard renderer uses CommonMark, which does not include footnotes. Install the Markdown Preview Enhanced extension to enable footnote rendering. Files with GFM footnotes will still render correctly on GitHub after you push them.

How do you write a multi-paragraph Markdown footnote?

Start the definition normally on the first line, then indent all continuation content by four spaces. Each four-space-indented block stays attached to the same footnote. Without the four-space indent, continuation paragraphs break out of the footnote and render as body text.