Markdown Footnote Syntax: A Complete Guide

Footnotes are something you see all the time in academic writing — those little superscript numbers like ¹ that you click to jump to the bottom of the page for extra details. If you're writing technical docs or research papers in Markdown, chances are you'll need this feature.

In this article, I'll share what I've learned from using markdown footnotes, starting with the basics and moving on to some gotchas that trip people up.

What Are Markdown Footnotes

A Markdown footnote is a superscript marker in your text that readers can click to jump to a detailed note at the bottom of the page. It works a lot like the citation markers you see on Wikipedia.

By the way, if you're looking to add hidden notes that don't show up in the rendered output, you want Markdown comments instead — footnotes are always visible, so don't mix them up.

Basic Markdown Footnote Syntax

Markdown footnotes have two parts: the reference marker (placed in your text) and the footnote definition (placed anywhere in your document).

Reference-Style Footnotes

This is the most common and widely supported markdown footnote syntax:

Here is some text that needs a footnote.[^1]

[^1]: This is the footnote content.

Rendered output:

Here is some text that needs a footnote.¹

---

¹ This is the footnote content.

Key points:

• Use [^label] in your text to mark the footnote position
• Define the footnote anywhere in the document with [^label]: Footnote content
• Labels can be numbers (1, 2) or words (note, source)
• Renderers auto-number based on order of appearance, so the label name doesn't affect the displayed number

Here's a pitfall I ran into: the label name must be exactly the same in both places. Once I wrote [^note1] in the text but typed [^note-1] in the definition — just one extra hyphen — and the footnote wouldn't show up at all. Took me a while to track that down.

Inline Footnotes

Pandoc and some parsers support a more compact inline syntax:

Here is a sentence.^[This is an inline footnote, no separate definition needed.]

Inline footnotes don't need a separate definition — the content goes right inside ^[...]. This works well for short notes.

One thing to keep in mind: inline footnotes ^[...] only work in Pandoc and a handful of editors. GitHub, GitLab, and most other platforms don't support them. If you need cross-platform compatibility, stick with the reference-style [^label].

Multi-Paragraph Footnotes

When a footnote is long enough to need multiple paragraphs, subsequent paragraphs must be indented with 4 spaces:

Here is a multi-paragraph footnote.[^long]

[^long]: This is the first paragraph of the footnote.
    This is the second paragraph, indented with 4 spaces.

    The third paragraph also needs 4-space indentation. You can use **bold** and [links](https://example.com) inside footnotes too.

Key rules:

• The first line goes right after the colon in the definition
• Subsequent paragraphs are indented with 4 spaces (not tabs)
• Paragraphs are separated by blank lines, which also need indentation

I hit a snag with this one: on GitHub I used tabs for indentation, and everything got mashed into a single paragraph. Switched to 4 spaces and it worked fine. Obsidian handles both tabs and spaces, but different platforms handle this differently. To play it safe, always use 4 spaces.

Footnote Label Naming Rules

Footnote labels are pretty flexible:

First reference.[^1] Second reference to the same footnote.[^1]

[^1]: This footnote is referenced twice.

For short documents, plain numbers like [^1] are fine. But if you're writing something with dozens of footnotes, semantic labels like [^smith2023] are much easier to maintain — you can tell at a glance which source each footnote refers to.

Where to Place Footnote Definitions

Footnote definitions can go anywhere in the document. The renderer collects them all and displays them at the bottom.

Some practical tips:

• Short docs: Put them at the end, easy to manage
• Long docs: Place them at the end of each section so you don't have to scroll back and forth
• Academic papers: All at the end, in order of appearance

## Section One

Some text here.[^a]

[^a]: Footnote for section one.

## Section Two

Some more text.[^b]

[^b]: Footnote for section two.

Platform Compatibility Table

Different Markdown parsers and platforms support footnotes very differently. I put together a compatibility table for the main ones:

✅ Supported　❌ Not supported　⚠️ Partial/unreliable

In the table above, GitHub, Obsidian, and Typora are platforms I've tested myself. Pandoc, Hugo, and Jekyll are based on their official docs. Yuque, Feishu, and CSDN are from community reports, so they might not be 100% accurate.

Oh, and about VS Code — its built-in Markdown preview doesn't support footnotes at all. I thought I had the syntax wrong and kept rewriting it over and over. Turns out it's a VS Code limitation. Installed the "Markdown Footnotes" extension and it worked right away. If you write Markdown in VS Code, install that extension first.

Footnotes vs Reference Links: Which to Use

Markdown has two syntaxes that look similar but serve different purposes:

<!-- Footnote: for supplementary notes -->
Here's a claim that needs a citation.[^1]

[^1]: Supporting evidence from a research paper.

<!-- Reference link: for external URLs -->
For more, see the [Markdown link](/markdown/link/) syntax guide.

<!-- You can also fake footnotes with HTML -->
Here's a note.<sup><a id="note1" href="#fn1">1</a></sup>

<span id="fn1">1. A manually created footnote.</span> [<a href="#note1">↑</a>]

Quick decision guide:

• Need supplementary notes or citations → use footnotes
• Need to link to another page → use Markdown links
• Platform doesn't support footnotes but you need superscript → use HTML <sup> tags

Markdown Formatting Inside Footnotes

Footnotes support most Markdown formatting:

Some text here.[^fmt]

[^fmt]: You can use **bold**, *italic*, `code`, and [links](https://example.com) inside footnotes.
    Code blocks work too:

        console.log("Code inside a footnote")

    And so do lists:

    - First item
    - Second item

Note that code blocks inside footnotes need 8 spaces of indentation (4 for footnote continuation + 4 for code block indentation).

Troubleshooting Common Issues

Footnotes Not Showing

Check these in order:

1. Label mismatch: [^note1] in text vs [^note-1] in definition — they must be identical
2. Missing space after colon: [^1]: content (need a space after the colon)
3. Platform support: Check the compatibility table above
4. Indentation: Subsequent paragraphs need 4 spaces, not tabs
5. Duplicate definitions: Each label can only be defined once; duplicates cause issues

Footnote Numbers Out of Order

Footnote numbers are generated in order of appearance in the text, regardless of what numbers you use in the labels:

Second paragraph.[^99]
First paragraph.[^1]

[^1]: First footnote.
[^99]: Second footnote.

After rendering, [^99] will display as 1 (because it appears first in the text), and [^1] will display as 2.

Multi-Paragraph Footnotes Merged Into One

Make sure subsequent paragraphs use 4 spaces for indentation, not tabs. Different parsers handle tabs inconsistently, so 4 spaces is the safest option.

Practical Tips

After using Markdown footnotes for a while, here are some habits I've picked up:

• For short docs, just use numbered labels [^1]. Don't overthink it. But for longer pieces with dozens of footnotes, go with semantic labels like [^smith2023] — otherwise you'll lose track of which footnote points to which source
• Keep footnote definitions at the end of the document for easy access, unless the doc is really long, in which case section-by-section works
• [^1] has way better compatibility than ^[], so stick with reference-style unless you have a specific reason not to
• Keep footnote content concise — if it's more than three paragraphs, it probably belongs in the main text
• Always preview on your target platform before publishing. Rendering can vary a lot between platforms

Wrapping Up

Honestly, the syntax for Markdown footnotes is pretty simple — you can learn it in seconds. The tricky part is all the details: a typo in a label, using tabs instead of spaces, a platform that doesn't support them... that's where the real frustration lives.

My advice: just start with [^1] and call it a day. You can learn the fancier syntax when you actually need it. This one syntax works on GitHub, Obsidian, Typora — pretty much everywhere.

Sources:

• Markdown Guide - Extended Syntax (Footnotes) (Authoritative Markdown community reference)
• GitHub Blog - Footnotes Now Supported (Official GitHub announcement)
• Stack Overflow - How to Add Footnotes to GitHub Flavored Markdown (153K+ views)
• Pandoc Manual - Footnotes (Official Pandoc documentation)