Markdown Footnotes

A Markdown footnote lets you add extra information without interrupting the flow of your main content. Instead of placing lengthy explanations, citations, or background details directly inside a paragraph, you insert a small footnote reference in the text and define the full note later in the document.

Footnotes are commonly used for:

• Technical documentation
• Tutorials and user guides
• Blog posts and long-form articles
• Research notes and academic writing
• Knowledge bases
• GitHub README files

Unlike standard Markdown links, footnotes keep readers focused on the current section while still making additional information available when needed.

If your goal is to send readers to another page instead of providing supporting information on the same page, use Markdown Links instead.

Why Use Markdown Footnotes?#

Footnotes improve readability by keeping paragraphs concise while still preserving important details that some readers may need.

They are useful for:

• Adding references and citations without cluttering the main content
• Explaining technical terms or abbreviations
• Including compatibility notes, warnings, or optional tips
• Providing background information without interrupting tutorials
• Keeping README files and documentation clean while still documenting important caveats

Footnotes work especially well when the additional information is helpful but not essential for every reader. This allows your main content to stay focused while making supporting details available only when needed.

A standard Markdown footnote consists of two parts:

1. A footnote reference placed in the text: [^id]
2. A matching footnote definition placed elsewhere in the document: [^id]: ...

Here's the basic syntax:

This sentence has a footnote.[^1]

[^1]: This is the footnote definition.

Output

The identifier inside [^...] can be a number (1, 2, 3) or a descriptive name (note, source, history), depending on the Markdown parser you are using.

💡 Compatibility note: Footnotes are not part of the original Markdown specification or core CommonMark. They are available in GitHub Flavored Markdown (GFM), Obsidian, and many documentation tools through extensions or additional parser support. If you're writing for multiple platforms, always preview the rendered output.

How Markdown Footnotes Work#

Markdown matches each footnote reference with its corresponding definition using the identifier inside [^...].

For example, when the reference [^1] appears in your content and a matching definition [^1]: exists later in the document, a Markdown renderer that supports footnotes typically:

• Converts the reference into a clickable footnote marker
• Collects all footnote definitions into a dedicated footnotes section (usually at the bottom of the page)
• Adds a back-reference link so readers can quickly return to the original reference

Most Markdown renderers display footnotes in the order their references first appear in the document, regardless of where the definitions are written. The definition itself only needs to use the same identifier.

If your Markdown renderer doesn't support footnotes, the raw syntax (such as [^1]) may appear instead of a formatted footnote.

Basic Footnote Example#

A basic footnote uses a numbered reference and a matching numbered definition.

Markdown makes documents easy to write.[^1]

[^1]: Markdown is a lightweight markup language.

Output

This standard reference-and-definition format offers the broadest compatibility across Markdown editors, documentation generators, and GitHub Flavored Markdown.

Once you know the basic syntax, these patterns cover the most common ways footnotes appear in documentation and long-form writing.

Named Footnotes#

Many Markdown implementations support descriptive (named) footnote identifiers instead of numbers.

Named footnotes are often easier to maintain in larger documents because the identifier describes the purpose of the note instead of relying on sequential numbering.

Markdown became popular in 2004.[^history]

[^history]: Markdown was created by John Gruber in 2004.

Output

Named identifiers improve readability while editing, but support varies between Markdown parsers. If maximum compatibility is important, numbered identifiers such as [^1], [^2], and [^3] remain the safest choice.

Multiple Footnotes#

To add multiple footnotes, give each one a unique identifier and provide a matching definition.

Install Node.js before continuing.[^1]
Use the LTS version for production.[^2]

[^1]: Version 20 or later is recommended.
[^2]: LTS releases receive longer security support.

Output

Although footnote definitions are commonly placed together at the end of a document, Markdown matches each footnote by its identifier rather than its position. Keeping all definitions in one place simply makes documents easier to edit and maintain.

Inline Footnotes#

Some Markdown flavors support inline footnotes, where the footnote content is written directly inside the reference instead of using a separate definition.

For example:

Markdown keeps documents readable.^[This is an inline footnote.]

Inline footnotes are convenient for short notes, but support is limited and varies significantly across Markdown implementations.

For the best compatibility across GitHub, documentation generators, note-taking apps, and Markdown editors, use the standard reference-and-definition syntax instead:

Markdown keeps documents readable.[^note]

[^note]: This is the footnote definition.

Multiple References to the Same Footnote#

Some Markdown parsers allow the same footnote to be referenced multiple times by using the same identifier.

Markdown is easy to learn.[^tip]
It also works well for README files.[^tip]

[^tip]: Use headings and short paragraphs for better readability.

Output

Support for multiple references to the same footnote varies by Markdown parser. If your target platform doesn't support reusable references, create separate footnotes instead (for example, [^tip-1] and [^tip-2]).

Always preview your document on the platform where it will be published to verify the rendered output.

Footnotes can include more than plain text. Links, inline code, and (on some platforms) larger block content are common in technical writing.

Footnotes with Links#

Footnote definitions often contain links to sources or external references.

CommonMark documents the core Markdown spec.[^spec]

[^spec]: CommonMark specification: https://commonmark.org

Output

External URLs inside footnotes are fine as plain text, especially when you want to avoid cluttering the paragraph with a long link. For link syntax in the main document, see Markdown Links.

Footnotes with Inline Code#

Inline code works naturally inside footnotes, which is useful for command explanations and technical clarifications.

Run the install command first.[^cmd]

[^cmd]: Use `npm install` to install dependencies.

Output

Footnotes with Code Blocks#

Some Markdown renderers allow block content (such as lists, blockquotes, or fenced code blocks) inside footnotes, while others support only plain text. When you need to include larger examples, always preview the rendered output on your target platform.

When supported, indent the block under the footnote definition:

Use a config file for reproducible builds.[^config]

[^config]: Example `config.json`:

    ```json
    {"mode":"production","minify":true}
    ```

If a long code block doesn't render correctly inside a footnote, move the example into the main document using Markdown Code Blocks and keep the footnote focused on the explanation instead.

Footnotes in Technical Docs#

Footnotes are a strong pattern for technical documentation because they keep the main steps readable while still allowing precise details.

Common uses include:

• Version requirements ("Node 20+ recommended")
• Platform caveats ("Windows paths differ")
• Extra references (spec links, RFC links)
• Optional tips (performance, security, debugging)

Install the CLI tool.[^1]

[^1]: Administrator permissions may be required on some systems.

This keeps the main instruction short while still documenting the caveat.

GitHub Flavored Markdown (GFM) supports standard footnote syntax using [^id] references and matching [^id]: definitions.

GitHub automatically renders footnote references as clickable superscript links and places the corresponding definitions in a Footnotes section near the end of the document.

If you're publishing the same Markdown on multiple platforms (GitHub, documentation sites, note-taking apps, or static site generators), preview the output because footnote support depends on the Markdown engine and enabled extensions.

For more GFM features, see GitHub Flavored Markdown.

Compatibility depends on the Markdown parser rather than the editor itself. Two applications may both support Markdown while rendering footnotes differently because they use different Markdown engines or extensions.

Footnotes work best when they add helpful context without becoming a second article at the bottom of the page.

Keep Footnotes Short#

Use footnotes for brief explanations and references. Put must-read information in the main content.

Keep Footnotes Optional#

Footnotes should provide supporting information—not essential instructions.

If readers must understand something to follow the document, include it in the main content instead of hiding it in a footnote.

Use Clear IDs#

• For short docs, numbered IDs ([^1], [^2]) are simple.
• For larger docs, named IDs ([^source], [^note]) can be easier to maintain.

Keep Definitions Together#

Place definitions at the end of the document (or end of a section) so they are easier to find and edit.

Preview Before Publishing#

Always preview your Markdown where it will be published. If you want a quick check, open the Markdown Editor and verify that every footnote renders correctly.

Footnote syntax is simple, but small mistakes can prevent rendering.

Missing Footnote Definition#

Incorrect (no definition):

This has a footnote.[^1]

Correct

This has a footnote.[^1]

[^1]: Add the definition somewhere later.

Reference and Definition Don't Match#

Incorrect

Text with a footnote.[^1]

[^one]: The ID does not match.

Correct

Text with a footnote.[^1]

[^1]: The ID matches exactly.

Duplicate Footnote IDs#

Using the same identifier for different footnotes can produce unexpected results.

Incorrect

[^note]: First explanation.

[^note]: Second explanation.

Correct

[^note1]: First explanation.

[^note2]: Second explanation.

Each footnote definition should use a unique identifier unless you're intentionally reusing the same reference.

Using a Platform That Doesn't Support Footnotes#

If your footnotes show as raw [^id] text, your Markdown renderer likely does not support footnotes (or needs an extension enabled).

Overusing Footnotes#

If every sentence has a footnote, readers may lose the main thread. Use footnotes for genuinely optional or supporting information.

Footnotes show up across many kinds of writing because they help balance readability with detail.

Documentation Note#

This tool runs entirely in your browser.[^privacy]

[^privacy]: Your content is never uploaded or stored.

Blog Source#

Markdown became widely adopted in the 2000s.[^source]

[^source]: Background reading: https://commonmark.org

Tutorial Tip#

Complete installation first.[^note]

[^note]: Administrator permissions may be required.

README Caveat#

This project supports multiple platforms.[^1]

[^1]: See the docs for the complete compatibility list.

Practice Markdown Footnotes#

The easiest way to learn Markdown footnotes is to create a small document and preview it as you write.

Open the Markdown Editor to test footnote rendering in real time, or use the Markdown Footnote Generator to generate correctly formatted references and definitions automatically.

Practice creating:

• One numbered footnote
• One named footnote
• Multiple footnotes in the same document
• A reusable footnote reference (where supported)
• A footnote containing inline code or a link

Summary#

Markdown footnotes let you add citations, explanations, references, and supporting information without interrupting the flow of your writing.

In this guide, you learned:

• What Markdown footnotes are
• Standard reference and definition syntax
• Numbered and named footnotes
• Multiple and reusable footnote references
• Using links, inline code, and code blocks in footnotes
• GitHub support and platform compatibility
• Best practices and common mistakes

For the best compatibility across Markdown editors and documentation platforms, use the standard [^id] reference with a matching [^id]: definition and always preview your document before publishing.