Footnotes
Footnotes solve one specific problem: the body of a document wants to run in a straight line, but some information — a source, a version number, the full name of a term — has to stay within reach. A footnote takes that information out of the flow and puts it at the end, leaving a small marker in its place. Readers who care click the marker and read the note; readers who do not are not interrupted by it.
The syntax is two halves that share a label. The reference goes where the information is mentioned, and the definition holds the information itself. The label is the link between them: whatever you write after the caret has to be the same on both sides. This page covers the two halves, where the definition belongs in the file, how the numbering is decided, the rules a label has to follow, and the fact that all of this is an extension rather than part of the Markdown standard.
A reference is written as a label in square brackets after a caret. A definition is the same label, followed by a colon and the content:
This is a footnote reference in the body[^note]
[^note]: This is the footnote content.<p>This is a footnote reference in the body<sup><a href="#user-content-fn-note" id="user-content-fnref-note" data-footnote-ref="" aria-describedby="footnote-label">1</a></sup></p>
<section data-footnotes="" class="footnotes"><h2 class="sr-only" id="footnote-label">Footnotes</h2>
<ol>
<li id="user-content-fn-note">
<p>This is the footnote content. <a href="#user-content-fnref-note" data-footnote-backref="" aria-label="Back to reference 1" class="data-footnote-backref">↩</a></p>
</li>
</ol>
</section>Two things happen in that output, and they happen in different places on the page. The reference in the body became a small superscript link carrying the number 1, pointing at the anchor of the footnote. The definition itself was moved to a separate section at the end of the document, listed as an ordered list, and each entry ends with a small arrow that takes the reader back to where the reference was. Notice that the number appears in the markup and nowhere in the source: you never write it, the renderer generates it and keeps it in step with the order of the references.
The definition can sit anywhere in the file. The renderer collects every definition, pulls them out of the flow, and places them all in the footnote section at the end of the document, in the order the references appear. A definition written in the middle of the document and the same definition written at the very end produce identical output. One corollary is worth knowing: a definition with no matching reference is dropped completely — the footnote section does not appear at all, and the note is lost without a word of warning — so a definition is only safe to write once the reference that points at it exists.
That said, put the definitions at the end of the document anyway. The rendering does not care where they are, but the source is read by people — by you in six months, by a reviewer, by someone using an editor that does not implement footnotes. A file whose footnotes are all gathered in one block at the bottom is far easier to scan than one where they are scattered through the prose.
The number is not the label, and it is not the order of the definitions. It is the order in which the references appear in the body. In the example below, the reference to b comes first, so b is footnote 1 and a is footnote 2 — even though the definition of a is written first:
First[^b] then second[^a]
[^a]: The note for a
[^b]: The note for b<p>First<sup><a href="#user-content-fn-b" id="user-content-fnref-b" data-footnote-ref="" aria-describedby="footnote-label">1</a></sup> then second<sup><a href="#user-content-fn-a" id="user-content-fnref-a" data-footnote-ref="" aria-describedby="footnote-label">2</a></sup></p>
<section data-footnotes="" class="footnotes"><h2 class="sr-only" id="footnote-label">Footnotes</h2>
<ol>
<li id="user-content-fn-b">
<p>The note for b <a href="#user-content-fnref-b" data-footnote-backref="" aria-label="Back to reference 1" class="data-footnote-backref">↩</a></p>
</li>
<li id="user-content-fn-a">
<p>The note for a <a href="#user-content-fnref-a" data-footnote-backref="" aria-label="Back to reference 2" class="data-footnote-backref">↩</a></p>
</li>
</ol>
</section>The labels a and b never appear in the output at all — they survive only as the id and href attributes that make the links work. The reader sees the number, and the number is the order of the reference. The same label may also be referenced more than once: both references then point at the same footnote and carry the same number, and the footnote gets one entry with a back arrow for each reference that points at it:
Body[^dup] and again[^dup]
[^dup]: A note that is referenced twice.<p>Body<sup><a href="#user-content-fn-dup" id="user-content-fnref-dup" data-footnote-ref="" aria-describedby="footnote-label">1</a></sup> and again<sup><a href="#user-content-fn-dup" id="user-content-fnref-dup-2" data-footnote-ref="" aria-describedby="footnote-label">1</a></sup></p>
<section data-footnotes="" class="footnotes"><h2 class="sr-only" id="footnote-label">Footnotes</h2>
<ol>
<li id="user-content-fn-dup">
<p>A note that is referenced twice. <a href="#user-content-fnref-dup" data-footnote-backref="" aria-label="Back to reference 1" class="data-footnote-backref">↩</a> <a href="#user-content-fnref-dup-2" data-footnote-backref="" aria-label="Back to reference 1-2" class="data-footnote-backref">↩<sup>2</sup></a></p>
</li>
</ol>
</section>The content of a footnote is parsed with the ordinary block syntax, so it can contain lists, code, and more than one paragraph. To add a second paragraph, indent it by four spaces so that it stays part of the footnote:
Body[^a]
[^a]: First paragraph.
Second paragraph.<p>Body<sup><a href="#user-content-fn-a" id="user-content-fnref-a" data-footnote-ref="" aria-describedby="footnote-label">1</a></sup></p>
<section data-footnotes="" class="footnotes"><h2 class="sr-only" id="footnote-label">Footnotes</h2>
<ol>
<li id="user-content-fn-a">
<p>First paragraph.</p>
<p>Second paragraph. <a href="#user-content-fnref-a" data-footnote-backref="" aria-label="Back to reference 1" class="data-footnote-backref">↩</a></p>
</li>
</ol>
</section>Two paragraphs end up inside one footnote entry, and the back arrow is attached to the last of them. The four-space indent is the same rule that keeps a paragraph inside a list item, and it works the same way here.
A label has to be a single word. It cannot contain a space, and it cannot be empty. When it does contain a space, the footnote syntax does not apply at all — the text is parsed as an ordinary link reference instead. The definition line becomes the link’s destination, and the reference in the body becomes a link:
Body[^a b]
[^a b]: Content<p>Body<a href="Content">^a b</a></p>This is the most misleading failure on the page, because the result still looks like a link. Nothing is broken, nothing is highlighted, and the text ^a b is right there in the paragraph — but the reader gets a link to the word “Content” instead of a footnote. If you see a caret and a bracket in the middle of your text after rendering, look for a space in the label. An empty label ends up the same way once it has a definition: [^]: Content turns the reference into a link to the word “Content”, and without a definition it simply stays in the text as [^].
A reference to a label that has no definition is neither removed nor turned into a footnote. It stays in the text exactly as it was written:
Body[^missing]<p>Body[^missing]</p>There is no warning and no broken link, so a missing definition is easy to miss while you are writing. It is also easy to spot once you look: the raw [^missing] sitting in the middle of a paragraph.
Footnote syntax is a GitHub Flavored Markdown extension. It is not part of CommonMark, the specification that defines what Markdown itself is, and it is not part of the plain-text flavour of Markdown that every tool claims to support. GitHub, most static site generators, and most modern editors implement it; a plain CommonMark renderer does not.
On a platform without support, the source survives as written and the reader sees [^1] in the middle of the sentence — a bracket and a caret that mean nothing to them. This is the same class of problem as a task list showing its brackets, and it is worth knowing before you rely on a footnote to carry a definition that matters.
One more detail about the output itself: the renderer writes a heading into the footnote section, and the heading it writes is the English word “Footnotes”. It is marked as visually hidden, so it does not appear on the page, but a screen reader will still announce it — including on a page whose language is not English.
| Written as | Actually renders as | Why |
|---|---|---|
[^a b] | an ordinary link | a label cannot contain a space |
[^missing] | the text, unchanged | there is no definition to attach it to |
| the same label twice | two references, one footnote | a label may be referenced repeatedly |
| a definition in the middle of the file | still at the end | the renderer moves every definition |
[^1] on a plain CommonMark renderer | the text, unchanged | footnotes are a GFM extension |
A footnote is a promise the reader cannot check. The reference looks like a link and the number looks like a footnote, so the reader assumes the note is there — and on a platform that does not implement footnotes, or in a label that picked up a space by accident, the note is simply missing while the page still looks finished. That is why the definition belongs at the end of the file where you can see it, why the label deserves a check before you publish, and why a footnote is the wrong place for information the reader must have: put that in the body, and use the footnote for the part they may want.
Rewrite the following sentence as Markdown. Requirements: add one footnote reference in the body; write the version number inside the footnote as inline code; and place the footnote definition after the sentence.
This tool has supported table syntax since version 1.0.Approach:
A footnote is two halves that share a label: the reference [^label] in the body, and the definition [^label]: content elsewhere in the file. The label must be identical on both sides and must not contain a space, otherwise the whole thing is parsed as a link reference instead. The number is generated by the renderer, so there is nothing to number by hand, and the content of a footnote accepts the ordinary inline syntax, which is why the version number can be written as inline code.
Steps:
- Put the reference at the end of the sentence, written as
[^ver]. Use plain letters in the label and do not put a space in it, or the reference will be parsed as a link. - Leave a blank line after the sentence, then write the definition on its own line as
[^ver]:followed by the text of the note. - Write the version number inside the note as inline code, that is, wrapped in a pair of backticks, so that it renders in a monospace font.
- Place the definition after the sentence, which is also where the renderer will put it in the output.
- Check the result: the sentence ends with a small superscript marker, the document ends with a footnote section holding one numbered note, and the version number inside the note is rendered as inline code.
Answer:
This tool has supported table syntax since version 1.0[^ver]
[^ver]: Table syntax is a GFM extension, so versions before `1.0` render it as an ordinary paragraph.You can now write both halves of a footnote, and you know that the label is the link between them and that the number is generated for you in the order the references appear. You know that the definitions are collected at the end of the document wherever you wrote them, and you know that a footnote can hold several paragraphs if you indent them. You can recognise the two silent failures — a label with a space in it becomes an ordinary link, and a reference without a definition stays in the text — and you know that the whole feature is a GFM extension rather than part of the standard, so it degrades to visible source on a platform that does not support it. That completes the advanced chapter; the next chapter goes back to the everyday syntax that every document starts with.