Markdown Footnote: Syntax, Examples & Platform Support

Basic Footnote Syntax

A footnote has two parts: a reference in the text, written as [^1], and a definition written as [^1]: Footnote text on its own line, usually at the bottom of the document. The renderer turns the reference into a superscript number and collects the definitions into a numbered list at the end.

Important: footnotes are not part of standard CommonMark or the original Markdown specification. They are an extended syntax feature supported by processors such as PHP Markdown Extra, Pandoc, and GitHub (since 2021). If your tool does not support them, [^1] shows up as literal text.

Markdown was created in 2004.[^1] It has since spread to almost every writing tool.[^2]

[^1]: Created by John Gruber, with contributions from Aaron Swartz.
[^2]: Including GitHub, Notion, and Obsidian.

Named Footnotes

The identifier does not have to be a number. You can use a word such as [^note] or [^source] to keep your source readable and easier to maintain. The identifier is only used to match the reference with its definition — the rendered output is still numbered sequentially (1, 2, 3…) in the order the references appear in the text.

Footnotes are an extension.[^extension] GitHub added support in 2021.[^github]

[^extension]: They are not part of CommonMark.
[^github]: Announced in the GitHub changelog.

Even though the labels are extension and github, the reader sees ¹ and ². Named labels are especially handy in long documents where renumbering numeric footnotes by hand would be error-prone.

Multi-Paragraph Footnotes

To put more than one paragraph in a footnote, indent the continuation paragraphs with 4 spaces or a tab beneath the definition. Separate the paragraphs with a blank line, just like in normal Markdown.

Footnotes can hold longer explanations.[^long]

[^long]: This is the first paragraph of the footnote.

    This is the second paragraph. It stays inside the same
    footnote because it is indented.

If you forget the indentation, the second paragraph becomes a normal paragraph in the main document instead of part of the footnote.

Footnotes with Other Elements

Footnote text can contain inline formatting such as bold, italic, links, and inline code. On processors that support indented continuation blocks, you can also add lists and fenced code blocks inside a footnote.

Bold, links, and inline code

Use a fenced block for multi-line snippets.[^tip]

[^tip]: **Tip:** see the [CommonMark spec](https://commonmark.org) and run `npm install` first.

Lists inside a footnote

The app supports several formats.[^formats]

[^formats]: Supported formats:

    - Markdown (.md)
    - Plain text (.txt)
    - MDX (.mdx)

Code block inside a footnote

Install it with a single command.[^install]

[^install]: Run this in Terminal:

    ```
    brew install --cask mdviewer
    ```

Rich content inside footnotes is the least portable part of the syntax. GitHub, Pandoc, and Obsidian handle it well; simpler processors may only support a single line of text. When in doubt, keep footnotes short.

Inline Footnotes

Some processors let you write the footnote text directly where it is referenced, using ^[text]. There is no separate definition to maintain, which is convenient for short notes. This is a Pandoc extension and is not widely supported: Pandoc and Obsidian render it, but GitHub and many other processors print the caret and brackets literally.

Inline notes are quick to write.^[This is an inline footnote.]

If you need your document to render correctly across many tools, prefer the standard [^1] reference-and-definition syntax.

Where Footnotes Appear

Footnote definitions can be placed anywhere in your source file, but the rendered output always collects them at the bottom of the document, below a horizontal rule, in the order the references appear in the text. Moving a definition higher or lower in the source does not move it in the preview.

First paragraph.[^a]

[^a]: Defined right after the first paragraph, but rendered here.

Second paragraph.[^b]

[^b]: Defined at the very end of the file.

Because the order is determined by the references, not the definitions, you never have to worry about the numbering. If you reference the same footnote twice, most processors reuse the same number and add multiple back-links.

Platform Support

Because footnotes are an extension and not part of CommonMark, support varies. Here is how the most popular tools handle them.

Common Mistakes

Forgetting the footnote definition

Every reference needs a matching definition. If you write [^1] in the text but never add [^1]: ..., the processor has nothing to link to and prints the reference as literal text.

Works.[^1]

[^1]: This definition exists.

Broken.[^2]

(no [^2]: definition anywhere, so [^2] renders as literal text)

Using spaces in the identifier

The identifier must not contain spaces or tabs. [^my note] is not recognized as a footnote reference. Use a single word, or join words with a hyphen or underscore: [^my-note].

[^my-note]    <-- works
[^my_note]    <-- works
[^my note]    <-- broken, space in identifier

Placing definitions in the middle of text

A definition in the middle of a paragraph flow works, because the renderer moves it to the bottom anyway. But it makes the source hard to read and easy to break (a definition must start on its own line). Keep all definitions together at the end of the document, or directly after the paragraph that references them, separated by blank lines.

Forgetting to indent continuation lines

For multi-paragraph footnotes, every continuation paragraph must be indented by 4 spaces or a tab. Without indentation, the text ends the footnote and appears as regular body text.

FAQ

How do I add a footnote in Markdown?

Add a reference such as [^1] in your text, then define it on its own line with [^1]: Your footnote text. The renderer shows a superscript number in the text and lists the footnote at the bottom of the document. Footnotes are an extended syntax feature, not part of standard CommonMark, so make sure your processor supports them.

Do GitHub README files support footnotes?

Yes. GitHub added footnote support to its Markdown rendering in September 2021, and it works in README files, issues, pull requests, and comments. Use the standard [^1] reference and [^1]: text definition syntax.

Can I use named footnotes instead of numbers?

Yes. Use any single-word label, such as [^source] or [^note-2], and define it with [^source]: text. The label is only used for matching — the rendered footnotes are still numbered sequentially in the order they appear. Avoid spaces in the label.

Preview Your Markdown with MDViewer

MDViewer is a native macOS app for reading and previewing Markdown files. Double-click any .md file in Finder and see it rendered instantly — footnotes, tables, code blocks, and more. Lite is free; Pro adds editing, Git history, and PDF export.

Requires macOS 13.0 or later. Intel and Apple Silicon.