Markdown Footnotes: References and Definitions That Render

Markdown Footnotes: References and Definitions That Render

A Markdown footnote has two parts: a [^1] reference typed where the note belongs in the text, and a [^1]: definition line sitting at the end of the file. Renderers that support the footnote extension turn each reference into a clickable superscript and collect every definition into a numbered list at the bottom of the page. Write both parts, keep the identifiers matching, and the note renders.

The catch: footnotes are an extension of Markdown, not part of core CommonMark. Whether a reader sees a superscript or the literal text [^1] depends entirely on the renderer. This guide covers the reference and definition syntax, named identifiers, placement rules, and which renderers support footnotes in Markdown today.

What footnotes do that inline links cannot

An inline link keeps the note inside the sentence. The citation text sits in the reading flow, and the reader either follows it or ignores it. A footnote does the opposite: the sentence stays clean, and the supporting material waits at the bottom of the document for anyone who wants it.

Compare the two patterns side by side:

Inline link: The 2026 survey confirms the trend [in the full report](<https://example.com/report.pdf>).
Footnote:    The 2026 survey confirms the trend[^1].
[^1]: Full methodology and sample size are described in the report.

Use a footnote when the content is optional to the sentence: a citation, a clarification of a term, a tangent, or a pointer to further reading. Use a link when the destination is part of the message. Footnote syntax and reference-style links are siblings: Markdown link syntax solves long URLs in prose by parking them in a definitions list, while footnotes park whole notes there.

Reference and definition syntax

The Markdown footnote syntax is a matched pair.

• Reference: a caret plus an identifier in square brackets, placed inline where the superscript should appear. Example: [^1].
• Definition: the same identifier, a colon, a space, then the note text, on its own line. Example: [^1]: Note text.

A worked example with two footnotes:

Markdown is a lightweight markup language[^1] created by John Gruber[^2].
[^1]: It uses simple punctuation to mark up plain text.
[^2]: Gruber released Markdown in 2004.

Three rules decide whether this renders:

1. The identifier in the reference and the definition must match exactly, including case.
2. The definition needs a space after the colon. [^1]:text fails on most processors.
3. Leave a blank line before and after the definitions block so processors detect it cleanly.

A definition can hold more than one paragraph. Indent the continuation by at least four spaces or one tab, and blockquotes and lists work inside the note:

The claim rests on the survey design[^multipara].
[^multipara]: The first paragraph states the sample.
    This second paragraph adds the limitation. Indent it at least four spaces.
    > Blockquotes and lists render inside footnotes too.

All examples in this article sit inside fenced code blocks so they copy cleanly; if you need the fence syntax itself, see Markdown code blocks.

Named footnotes and repeated references

Identifiers do not have to be numbers. Any word works as long as it contains no spaces or tabs:

Here is a numbered footnote[^1] and a named footnote[^survey].
[^1]: A regular footnote.
[^survey]: Points to the survey methodology section.

Do not expect the identifier to reach the reader. Most processors renumber footnotes into consecutive numbers in order of appearance, so [^survey] may display as superscript 2. That is expected behavior, not a bug.

Because the connection runs through the identifier, you can repeat the same reference in more than one place and both markers point at the single definition:

The sample was regional[^sample]. A follow-up wave confirmed the result[^sample].
[^sample]: 1,200 respondents across three cities, fielded in March 2026.

Processors in the Pandoc and GitHub (GFM) lineages follow the identifier this way. If your renderer does not, a repeated or unmatched identifier falls back to literal text, so test the pattern on a small file before relying on it in a long document.

Where definitions go and how renderers handle them

Placement is more forgiving than most people expect:

• The definition line can sit anywhere in the file. Most writers collect all definitions at the bottom, often after a --- divider or a ## Footnotes heading, for easier maintenance.
• The renderer collects the definitions, renumbers them, and outputs them at the end of the document regardless of where the lines live in the source. Moving a definition does not change the rendered position.
• For very long documents, you can group footnotes per chapter with chapter-scoped identifiers such as [^1-1] and [^2-1], keeping each chapter's notes near its own text while the renderer still gathers them at the end.
• If the reference identifier and the definition identifier do not match exactly, the marker displays as literal text. An unmatched [^7] in prose simply renders as [^7], which keeps the file readable even when the extension is missing.

One form to avoid: inline footnotes like ^[Note text directly in the sentence.] exist in some processors (GitLab, Pandoc, kramdown, Hugo) but are not standard. They break portability, because the note text is embedded in the sentence rather than collected at the end of the file.

Renderer support: extension, not core

Core CommonMark does not define footnotes, so every working implementation is an extension carried forward from the Pandoc, MultiMarkdown, and PHP Markdown Extra lineage. Tools built on that lineage, such as GitBook, Pandoc, and RStudio, handle footnotes well.

The support picture across common platforms:

If your target platform shows [^1] as plain text, the renderer lacks the extension. Your options are to preprocess with a tool that supports the extension (Pandoc with its footnotes feature, or a Markdown library with a footnote plugin), or to move the note inline in parentheses where it fits. Before publishing, confirm which flavor your platform uses rather than assuming.

A local-file workflow in Fylune

For research notes and source-cited documents, the footnote pair fits the local-file workflow directly:

1. Keep the note as an ordinary .md file inside your project folder. Fylune is a local-first document workspace: the selected folder stays the source of truth, and the file opens without an account or network.
2. Write [^1] inline while drafting and drop the definitions at the bottom of the file. Rich Markdown and MDX render inside the document experience, and the syntax remains plain text in the file, so the note belongs to the file, not to a proprietary database.
3. External tools keep working on the same file. Git, agents such as Codex or Claude Code, and any other local editor see the identical Markdown, so a footnote written in Fylune survives round-trips and stays reviewable.
4. Ship or share the file with confidence: because definitions are collected at render time by whatever engine displays the document, the file carries the full source structure wherever it goes.

One honest limitation: footnote display depends on the Markdown engine in each editor, and the support table above reflects the extension ecosystem rather than a product feature list. Verify footnote rendering on a small sample file in the editor you actually publish from. The underlying file is plain Markdown either way, so nothing is lost if a renderer lacks the extension.

The rendered marker is styled as raised text, the visual sibling of superscript formatting covered in Markdown superscript and subscript workarounds.

Quick reference

Footnotes in Markdown come down to one habit: write the reference where the idea appears, park the definition at the end of the file, and confirm the renderer supports the extension before you publish.

Keep footnotes rendering in your local files: Fylune keeps your Markdown and MDX in ordinary project files while rich Markdown renders inside the document experience. Download Fylune for macOS.

Sources

• How to Use Footnotes in Markdown: A Guide, MarkDown Tools blog: the two-part reference and definition system, identifier matching, and flavor differences across platforms.
• Markdown Footnote Extension, markdownlang.com: footnote identifiers, multi-paragraph indentation, renumbering behavior, placement, and the platform support table.
• Issue 100: footnote validation in the VS Code Markdown language service, GitHub: how renderers validate the reference and definition structure of footnote syntax.