Markdown Footnotes

A Markdown footnote lets you add extra information without interrupting the main text.

Instead of placing explanations, citations, or background context inside a paragraph, you place a small footnote reference in the sentence and write the full note later (usually at the bottom of the document).

Footnotes are commonly used in:

• Technical documentation
• Tutorials and user guides
• Blog posts
• Research notes
• Knowledge bases
• README files

If you want to link readers to another page (instead of keeping them on the same page), use Markdown Links instead.

Footnotes improve readability by keeping paragraphs short while still preserving important details.

They help you:

• Add references and citations without clutter
• Explain technical terms without derailing the flow
• Add optional tips, warnings, or compatibility notes
• Keep tutorials focused while still providing extra context
• Keep README introductions clean while still documenting important caveats

Footnotes are especially useful when readers should stay focused on the current content instead of jumping away to external links.

A Markdown footnote has two parts:

• A reference in the text: [^id]
• A matching definition later in the document: [^id]: ...

Here is the basic syntax pattern:

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 name (source, note, history) depending on platform support.

Markdown connects each footnote reference to its matching definition by identifier.

When the reference [^1] appears in your text and the definition [^1]: ... appears later, a Markdown renderer that supports footnotes will:

• Turn the reference into a clickable marker
• Render the footnote content in a footnotes section (often at the bottom)
• Provide a back-reference so readers can jump back to where they were reading

Footnote support is not part of core CommonMark, so some basic parsers will show the raw [^1] text instead of rendering a footnote.

A simple footnote is a numbered reference plus a numbered definition.

Markdown makes documents easy to write.[^1]

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

Output

Many Markdown implementations support named (custom) footnote IDs.

Named footnotes are easier to maintain in large documents because the identifier describes the note.

Markdown became popular in 2004.[^history]

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

Output

If your platform does not support named IDs, prefer numbered IDs like [^1], [^2], and [^3].

To add multiple footnotes, give each footnote a unique identifier and write a matching definition for each one.

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

Many authors place all footnote definitions together at the end of the document for easier editing.

Some Markdown flavors support inline footnotes, where the footnote content is written in the reference itself.

If your platform supports it, it can look like this:

Markdown keeps documents readable. ^[This is an inline footnote in flavors that support it.]

Inline footnotes are convenient for quick notes, but support varies widely. For maximum compatibility, use the standard reference + definition format:

Markdown keeps documents readable.[^note]

[^note]: This is the footnote definition.

Some platforms allow reusing the same footnote by referencing the same identifier multiple times.

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

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

Output

If your renderer does not support multiple references to one footnote, use separate footnotes instead (for example [^tip-1] and [^tip-2]).

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.

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

Some Markdown renderers allow block content (like lists or code blocks) inside footnotes, but support varies.

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 the code block does not render correctly on your platform, keep footnotes short and put larger code samples in the main content using Markdown Code Blocks.

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)

Example:

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 supports footnotes in Markdown documents such as README files.

That means standard footnote syntax using [^id] references and matching [^id]: definitions typically renders correctly on GitHub.

If you're writing for multiple platforms (GitHub + a docs site + a note app), always preview the final output because footnote support can differ between renderers.

Platform	Footnotes Supported
GitHub	✅
GitLab	Varies
VS Code Preview	Varies
Obsidian	✅
Docusaurus	✅ (with plugins/MDX config)
MkDocs	✅ (with extensions)
Hugo	Varies
Astro Starlight	Varies
CommonMark-only parsers	❌

Footnotes are not part of core CommonMark, so compatibility depends on the Markdown engine your platform uses and which extensions are enabled.

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.

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.

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.

The fastest way to learn footnotes is by writing and previewing them.

• Use the Markdown Editor for live rendering.
• Use the Markdown Footnote Generator to generate correct syntax quickly.

Try writing:

• One numbered footnote
• One named footnote
• Two different footnotes in the same paragraph
• A reusable footnote reference (if your platform supports it)

Markdown footnotes let you add citations, references, and extra context without making paragraphs harder to read.

In this guide, you learned:

• What footnotes are and why they're useful
• The reference + definition syntax
• Numbered vs named footnote IDs
• Multiple footnotes and reusing the same footnote
• Using links and inline code in footnotes
• GitHub support and platform compatibility
• Best practices and common mistakes

When in doubt, choose the standard [^id] reference + [^id]: definition pattern and preview the output on your target platform.

Continue learning Markdown with these guides:

• Markdown Basics — core concepts for beginners
• Markdown Cheat Sheet — quick syntax lookup
• Markdown Syntax — complete reference with examples
• Markdown Headings — document structure with H1–H6
• Markdown Paragraphs — blank lines and spacing
• Markdown Lists — ordered, unordered, nested, mixed, and task lists
• Markdown Links — inline, reference, and relative links
• Markdown Images — syntax, URLs, alt text, and GitHub paths
• Markdown Tables — syntax, alignment, and GitHub GFM
• Markdown Code Blocks — fenced blocks and syntax highlighting
• Markdown Blockquotes — syntax, nesting, and GitHub callouts
• Markdown Horizontal Rules — section dividers with ---, ***, and ___
• Markdown HTML — use HTML tags inside Markdown documents
• Markdown Task Lists — checkbox syntax, nested checklists, and GitHub GFM
• Markdown Footnotes — references, citations, and GitHub GFM support
• GitHub Markdown — GFM syntax, README examples, and GitHub-specific features
• Markdown Footnotes — references, citations, and footnote syntax