Footnotes in Markdown

A footnote is two halves that find each other by label: a marker in the text, and a definition anywhere else in the document. The renderer collects the definitions, numbers them in the order the markers appear and puts them at the bottom of the page with a link back.

Note that this is an extension, not part of the original Markdown, so support varies. The preview panel below renders footnotes as literal text — which is exactly what you will see in a parser that does not support them, and a useful thing to have looked at once.

Markdown was created in 2004.[^1] It was designed to be
readable as plain text.[^design]

[^1]: By John Gruber, with input from Aaron Swartz.
[^design]: "A Markdown-formatted document should be
    publishable as-is, as plain text."

The syntax

Some claim that needs a source.[^1]

[^1]: The source.

• The marker is [^label], inline where you want the number to appear.
• The definition is [^label]: text, on its own line.
• The label is not the number. [^gruber] is perfectly valid and renders as 1 if it is the first footnote in the document. Use words — they survive reordering, and [^1], [^2], [^3] need renumbering the moment you insert one.

Definitions can go anywhere. Putting them at the bottom is conventional; putting each one just below the paragraph that references it is far easier to maintain in a long document. The output is identical either way.

Multi-paragraph footnotes

Indent the continuation by four spaces:

Here is the claim.[^long]

[^long]: The first paragraph of the note.

    The second paragraph, indented four spaces.

The second paragraph, indented four spaces.

Where footnotes work

They are not in CommonMark, so this is a compatibility question:

• Supported: most static site generators, most note-taking and Markdown editor apps, pandoc, and the majority of tools that export to PDF or EPUB.
• Not supported: GitHub .md files rendered in a repository view historically ignored them, though GitHub has since added support in most contexts. Minimal parsers and many web preview widgets still do not.

If the target does not support them, the markers render as literal [^1] in the text and the definitions as ordinary paragraphs — visible, ugly, but not destructive.

When footnotes are the wrong tool

Footnotes suit long-form writing: papers, essays, documentation with citations. They suit a README badly. If the note is short and directly useful, an inline parenthesis reads better than making someone jump to the bottom of the page and back.

The good test: if the reader must read the note to follow the argument, it is not a footnote — it belongs in the sentence.

The portable alternative

Where footnotes are not supported, a section at the end plus anchor links does the same job with universal syntax:

Some claim.[<sup>1</sup>](#note-1)

## Notes

<a id="note-1"></a>1. The source.

It costs raw HTML for the anchor, and it is more work. Use it only when you know the target lacks footnote support.

Common mistakes

Defining a footnote that is never referenced. Most renderers silently drop it. Your note disappears from the output with no warning.

Referencing a label with no definition. The marker renders as literal [^1] text.

Numbering by hand. The label is not the number. Use words and let the renderer count.

Continuation indented by two spaces. Footnote continuations need four, unlike list items.

Assuming they work everywhere. Check your target before you write fifty of them.

FAQ

How do I add a footnote in Markdown?

Put [^label] where the marker should appear and [^label]: your note on its own line elsewhere in the document. The renderer numbers the markers in order of appearance and gathers the notes at the bottom.

Does the footnote label have to be a number?

No, and it is better if it is not. [^gruber] works and renders as whatever number its position calls for. Word labels survive reordering; numeric ones have to be renumbered by hand.

Do footnotes work on GitHub?

In most contexts now, yes — but historically they were ignored in repository file views, and many minimal parsers still do not support them. Where unsupported, the markers appear as literal [^1] text.

How do I write a footnote with several paragraphs?

Indent each continuation paragraph by four spaces under the definition. Anything indented that far belongs to the footnote.

Are footnotes part of standard Markdown?

No. They are an extension, absent from both the original 2004 syntax and from CommonMark, though widely implemented by static site generators, editors and document converters.