Footnotes — Notes That Don't Interrupt

~10 min · markdown, footnotes, pandoc

Level 0Plaintext

0 XP0/64 lessons0/12 achievements

0/100 XP to next level100 XP to go0% complete

Footnotes keep the main line clean

Footnotes let you attach an aside to a word without breaking the prose. The reference syntax is [^id]; the definition is [^id]: footnote body placed anywhere in the file. Renderers collect definitions, number them in the order they're referenced, and emit a footnote section.

Multi-paragraph footnotes

A footnote can span multiple paragraphs. Indent continuation paragraphs with 4 spaces (or 1 tab) to keep them attached to the same footnote.

Where footnotes live (and don't)

Footnotes are not in CommonMark. They are supported by GFM (since 2021), pandoc, MultiMarkdown, and most modern static-site generators. If you ship to a strict CommonMark target, fall back to plain parenthetical asides or end-of-section notes.

Principle: a footnote should add context the reader can safely skip. If the information is essential, put it in the main line. Footnotes are not a place to bury inconvenient truths.

Code

Single-line footnotes·markdown

Markdown was created in 2004[^gruber] and standardized as CommonMark[^cm].

[^gruber]: By John Gruber and Aaron Swartz.
[^cm]: First spec published 2014, current version 0.31.2.

Multi-paragraph footnote·markdown

The Norway problem[^norway] is YAML's most famous gotcha.

[^norway]: In YAML 1.1, unquoted `no` parses as boolean false.

    So `country: NO` reads as `country: False`. The fix is to
    quote the string or upgrade to YAML 1.2 where this was removed.

Order doesn't matter (definitions can come anywhere)·markdown

[^cm]: First spec published 2014.

# Document title

Markdown is from 2004[^gruber] and standardized as CommonMark[^cm].

[^gruber]: By John Gruber and Aaron Swartz.

External links

Exercise

Take a paragraph from one of your existing docs that has parenthetical asides ('(see also: ...)' or 'NB: ...'). Convert each aside to a footnote with a semantic ID. Read both versions side-by-side. Notice how much the main line breathes once the asides move to the bottom.

Progress

Progress is local-only — sign in to sync across devices.

← PreviousStrikethrough, Autolinks & Inline References Next →Alerts — > [!NOTE], [!WARNING], and Friends

Spotted a bug or have feedback on this page?Report an Issue

Comments 0

🔔 Reply notifications (sign in)

No comments yet — be the first.