A footnote is a note that’s set apart from the main text. A numbered mark in the text refers to it. Comrak collects footnotes into a numbered list at the end of the document, with links from each mark to its footnote and back again. Use footnotes for asides, citations, or anything else that would interrupt the text around it.
The GitHub Flavored Markdown spec doesn’t describe footnotes, but cmark-gfm, its reference implementation, supports them, and Comrak’s footnotes follow its design. This document describes Comrak’s footnotes, which can differ from cmark-gfm’s. GitLab uses Comrak’s footnotes, so this document is also the canonical spec for GitLab Flavored Markdown footnotes.
To enable footnotes, pass -e footnotes on the command line, or set extension.footnotes in the options struct. --gfm doesn’t enable them.
<p>Hi<supclass="footnote-ref"><ahref="#fn-x"id="fnref-x"data-footnote-ref>1</a></sup>.</p><sectionclass="footnotes"data-footnotes><ol><liid="fn-x"><p>A greeting. <ahref="#fnref-x"class="footnote-backref"data-footnote-backrefdata-footnote-backref-idx="1"aria-label="Back to reference 1">↩</a></p></li></ol></section>
Hi[^x].
[^x]:
A greeting.
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><textxml:space="preserve">Hi</text><footnote_referencelabel="x"/><textxml:space="preserve">.</text></paragraph><footnote_definitionlabel="x"><paragraph><textxml:space="preserve">A greeting.</text></paragraph></footnote_definition></document>
Syntax
A footnote has two parts: a footnote reference in the text, and a footnote definition that holds the footnote’s content. A reference can come before or after its definition.
Footnote labels
A footnote label is one or more characters other than a space, a tab, a line ending, or ]. Labels may contain punctuation and characters outside ASCII:
<p>A<supclass="footnote-ref"><ahref="#fn-a.b-c_d"id="fnref-a.b-c_d"data-footnote-ref>1</a></sup> and B<supclass="footnote-ref"><ahref="#fn-%C3%BCber"id="fnref-%C3%BCber"data-footnote-ref>2</a></sup>.</p><sectionclass="footnotes"data-footnotes><ol><liid="fn-a.b-c_d"><p>Punctuation. <ahref="#fnref-a.b-c_d"class="footnote-backref"data-footnote-backrefdata-footnote-backref-idx="1"aria-label="Back to reference 1">↩</a></p></li><liid="fn-%C3%BCber"><p>Not ASCII. <ahref="#fnref-%C3%BCber"class="footnote-backref"data-footnote-backrefdata-footnote-backref-idx="2"aria-label="Back to reference 2">↩</a></p></li></ol></section>
A[^a.b-c_d] and B[^über].
[^a.b-c_d]:
Punctuation.
[^über]:
Not ASCII.
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><textxml:space="preserve">A</text><footnote_referencelabel="a.b-c_d"/><textxml:space="preserve"> and B</text><footnote_referencelabel="über"/><textxml:space="preserve">.</text></paragraph><footnote_definitionlabel="a.b-c_d"><paragraph><textxml:space="preserve">Punctuation.</text></paragraph></footnote_definition><footnote_definitionlabel="über"><paragraph><textxml:space="preserve">Not ASCII.</text></paragraph></footnote_definition></document>
A label can’t contain whitespace. Neither of these lines is a footnote reference or a footnote definition:
<p>Foo.[^one two]</p><p>[^one two]: Here is the footnote.</p>
Foo.\[^one two\]\[^one two\]: Here is the footnote.
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><textxml:space="preserve">Foo.[^one two]</text></paragraph><paragraph><textxml:space="preserve">[^one two]: Here is the footnote.</text></paragraph></document>
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><textxml:space="preserve">Foo.[^]</text></paragraph><paragraph><textxml:space="preserve">[^]: Here is the footnote.</text></paragraph></document>
A footnote reference matches a footnote definition when their labels are the same, ignoring case. The footnote takes its label’s case from its definition:
<p>Here is a footnote reference.<supclass="footnote-ref"><ahref="#fn-aB"id="fnref-aB"data-footnote-ref>1</a></sup> and <supclass="footnote-ref"><ahref="#fn-aB"id="fnref-aB-2"data-footnote-ref>1</a></sup></p><sectionclass="footnotes"data-footnotes><ol><liid="fn-aB"><p>Here is the footnote. <ahref="#fnref-aB"class="footnote-backref"data-footnote-backrefdata-footnote-backref-idx="1"aria-label="Back to reference 1">↩</a><ahref="#fnref-aB-2"class="footnote-backref"data-footnote-backrefdata-footnote-backref-idx="1-2"aria-label="Back to reference 1-2">↩<supclass="footnote-ref">2</sup></a></p></li></ol></section>
Here is a footnote reference.[^aB] and [^aB]
[^aB]:
Here is the footnote.
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><textxml:space="preserve">Here is a footnote reference.</text><footnote_referencelabel="aB"/><textxml:space="preserve"> and </text><footnote_referencelabel="aB"/></paragraph><footnote_definitionlabel="aB"><paragraph><textxml:space="preserve">Here is the footnote.</text></paragraph></footnote_definition></document>
Whitespace at either end of the reference’s label is also ignored:
<p>A<supclass="footnote-ref"><ahref="#fn-a"id="fnref-a"data-footnote-ref>1</a></sup>, B<supclass="footnote-ref"><ahref="#fn-a"id="fnref-a-2"data-footnote-ref>1</a></sup> and C<supclass="footnote-ref"><ahref="#fn-a"id="fnref-a-3"data-footnote-ref>1</a></sup>.</p><sectionclass="footnotes"data-footnotes><ol><liid="fn-a"><p>Note. <ahref="#fnref-a"class="footnote-backref"data-footnote-backrefdata-footnote-backref-idx="1"aria-label="Back to reference 1">↩</a><ahref="#fnref-a-2"class="footnote-backref"data-footnote-backrefdata-footnote-backref-idx="1-2"aria-label="Back to reference 1-2">↩<supclass="footnote-ref">2</sup></a><ahref="#fnref-a-3"class="footnote-backref"data-footnote-backrefdata-footnote-backref-idx="1-3"aria-label="Back to reference 1-3">↩<supclass="footnote-ref">3</sup></a></p></li></ol></section>
A[^a], B[^a] and C[^a].
[^a]:
Note.
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><textxml:space="preserve">A</text><footnote_referencelabel="a"/><textxml:space="preserve">, B</text><footnote_referencelabel="a"/><textxml:space="preserve"> and C</text><footnote_referencelabel="a"/><textxml:space="preserve">.</text></paragraph><footnote_definitionlabel="a"><paragraph><textxml:space="preserve">Note.</text></paragraph></footnote_definition></document>
Otherwise, labels must match exactly as they’re written in the source. A backslash escape or an entity reference in a label isn’t interpreted, and inline syntax in a label doesn’t stop it matching. Here, [^a] doesn’t match the definition labelled a, but [^`b`] matches the definition labelled `b`:
<p>A[^a] and B<supclass="footnote-ref"><ahref="#fn-%60b%60"id="fnref-%60b%60"data-footnote-ref>1</a></sup>.</p><sectionclass="footnotes"data-footnotes><ol><liid="fn-%60b%60"><p>Backticks. <ahref="#fnref-%60b%60"class="footnote-backref"data-footnote-backrefdata-footnote-backref-idx="1"aria-label="Back to reference 1">↩</a></p></li></ol></section>
A\[^a\] and B[^`b`].
[^`b`]:
Backticks.
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><textxml:space="preserve">A[^a] and B</text><footnote_referencelabel="`b`"/><textxml:space="preserve">.</text></paragraph><footnote_definitionlabel="`b`"><paragraph><textxml:space="preserve">Backticks.</text></paragraph></footnote_definition></document>
Footnote definitions
A footnote definition begins with a line that has up to three spaces of indentation, then [^, a footnote label, and ]:. Any spaces or tabs after the colon are skipped, and the footnote’s content begins with what follows.
The content is a sequence of blocks, like a list item’s. Later lines belong to the definition if they’re blank, or indented by four or more spaces:
<p>A<supclass="footnote-ref"><ahref="#fn-a"id="fnref-a"data-footnote-ref>1</a></sup>.</p><sectionclass="footnotes"data-footnotes><ol><liid="fn-a"><p>First paragraph.</p><p>Second paragraph. <ahref="#fnref-a"class="footnote-backref"data-footnote-backrefdata-footnote-backref-idx="1"aria-label="Back to reference 1">↩</a></p></li></ol></section>
A[^a].
[^a]:
First paragraph.
Second paragraph.
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><textxml:space="preserve">A</text><footnote_referencelabel="a"/><textxml:space="preserve">.</text></paragraph><footnote_definitionlabel="a"><paragraph><textxml:space="preserve">First paragraph.</text></paragraph><paragraph><textxml:space="preserve">Second paragraph.</text></paragraph></footnote_definition></document>
<p>A<supclass="footnote-ref"><ahref="#fn-a"id="fnref-a"data-footnote-ref>1</a></sup>.</p><p>Not in the footnote.</p><sectionclass="footnotes"data-footnotes><ol><liid="fn-a"><p>First paragraph. <ahref="#fnref-a"class="footnote-backref"data-footnote-backrefdata-footnote-backref-idx="1"aria-label="Back to reference 1">↩</a></p></li></ol></section>
A[^a].
Not in the footnote.
[^a]:
First paragraph.
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><textxml:space="preserve">A</text><footnote_referencelabel="a"/><textxml:space="preserve">.</text></paragraph><paragraph><textxml:space="preserve">Not in the footnote.</text></paragraph><footnote_definitionlabel="a"><paragraph><textxml:space="preserve">First paragraph.</text></paragraph></footnote_definition></document>
<p>A<supclass="footnote-ref"><ahref="#fn-a"id="fnref-a"data-footnote-ref>1</a></sup>.</p><sectionclass="footnotes"data-footnotes><ol><liid="fn-a"><p>First line,
second line. <ahref="#fnref-a"class="footnote-backref"data-footnote-backrefdata-footnote-backref-idx="1"aria-label="Back to reference 1">↩</a></p></li></ol></section>
A[^a].
[^a]:
First line,
second line.
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><textxml:space="preserve">A</text><footnote_referencelabel="a"/><textxml:space="preserve">.</text></paragraph><footnote_definitionlabel="a"><paragraph><textxml:space="preserve">First line,</text><softbreak/><textxml:space="preserve">second line.</text></paragraph></footnote_definition></document>
The content may begin on a later line, and may begin with any kind of block:
<p>A<supclass="footnote-ref"><ahref="#fn-a"id="fnref-a"data-footnote-ref>1</a></sup> and B<supclass="footnote-ref"><ahref="#fn-b"id="fnref-b"data-footnote-ref>2</a></sup>.</p><sectionclass="footnotes"data-footnotes><ol><liid="fn-a"><p>On the next line. <ahref="#fnref-a"class="footnote-backref"data-footnote-backrefdata-footnote-backref-idx="1"aria-label="Back to reference 1">↩</a></p></li><liid="fn-b"><blockquote><p>A block quote.</p></blockquote><ahref="#fnref-b"class="footnote-backref"data-footnote-backrefdata-footnote-backref-idx="2"aria-label="Back to reference 2">↩</a></li></ol></section>
A[^a] and B[^b].
[^a]:
On the next line.
[^b]:
> A block quote.
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><textxml:space="preserve">A</text><footnote_referencelabel="a"/><textxml:space="preserve"> and B</text><footnote_referencelabel="b"/><textxml:space="preserve">.</text></paragraph><footnote_definitionlabel="a"><paragraph><textxml:space="preserve">On the next line.</text></paragraph></footnote_definition><footnote_definitionlabel="b"><block_quote><paragraph><textxml:space="preserve">A block quote.</text></paragraph></block_quote></footnote_definition></document>
<p>A<supclass="footnote-ref"><ahref="#fn-a"id="fnref-a"data-footnote-ref>1</a></sup>.</p><sectionclass="footnotes"data-footnotes><ol><liid="fn-a"><ahref="#fnref-a"class="footnote-backref"data-footnote-backrefdata-footnote-backref-idx="1"aria-label="Back to reference 1">↩</a></li></ol></section>
A[^a].
[^a]:
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><textxml:space="preserve">A</text><footnote_referencelabel="a"/><textxml:space="preserve">.</text></paragraph><footnote_definitionlabel="a"/></document>
<p>A<supclass="footnote-ref"><ahref="#fn-a"id="fnref-a"data-footnote-ref>1</a></sup>.</p><sectionclass="footnotes"data-footnotes><ol><liid="fn-a"><p>Note. <ahref="#fnref-a"class="footnote-backref"data-footnote-backrefdata-footnote-backref-idx="1"aria-label="Back to reference 1">↩</a></p></li></ol></section>
A[^a].
[^a]:
Note.
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><textxml:space="preserve">A</text><footnote_referencelabel="a"/><textxml:space="preserve">.</text></paragraph><footnote_definitionlabel="a"><paragraph><textxml:space="preserve">Note.</text></paragraph></footnote_definition></document>
The colon must directly follow the ], but the content needn’t be separated from the colon:
<p>A[^a] and B<supclass="footnote-ref"><ahref="#fn-b"id="fnref-b"data-footnote-ref>1</a></sup>.</p><p>[^a] : Not a definition.</p><sectionclass="footnotes"data-footnotes><ol><liid="fn-b"><p>Note. <ahref="#fnref-b"class="footnote-backref"data-footnote-backrefdata-footnote-backref-idx="1"aria-label="Back to reference 1">↩</a></p></li></ol></section>
A\[^a\] and B[^b].
\[^a\] : Not a definition.
[^b]:
Note.
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><textxml:space="preserve">A[^a] and B</text><footnote_referencelabel="b"/><textxml:space="preserve">.</text></paragraph><paragraph><textxml:space="preserve">[^a] : Not a definition.</text></paragraph><footnote_definitionlabel="b"><paragraph><textxml:space="preserve">Note.</text></paragraph></footnote_definition></document>
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><textxml:space="preserve">A[^a].</text></paragraph><code_blockxml:space="preserve">[^a]: Code.
</code_block></document>
A footnote definition may appear anywhere a block may, including inside a block quote, a list item, or another footnote definition. Comrak moves it to the footnotes at the end of the document:
<blockquote><p>A<supclass="footnote-ref"><ahref="#fn-a"id="fnref-a"data-footnote-ref>1</a></sup> and B<supclass="footnote-ref"><ahref="#fn-b"id="fnref-b"data-footnote-ref>2</a></sup>.</p></blockquote><sectionclass="footnotes"data-footnotes><ol><liid="fn-a"><p>Inside a block quote. <ahref="#fnref-a"class="footnote-backref"data-footnote-backrefdata-footnote-backref-idx="1"aria-label="Back to reference 1">↩</a></p></li><liid="fn-b"><p>Inside a footnote definition. <ahref="#fnref-b"class="footnote-backref"data-footnote-backrefdata-footnote-backref-idx="2"aria-label="Back to reference 2">↩</a></p></li></ol></section>
> A[^a] and B[^b].
[^a]:
Inside a block quote.
[^b]:
Inside a footnote definition.
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><block_quote><paragraph><textxml:space="preserve">A</text><footnote_referencelabel="a"/><textxml:space="preserve"> and B</text><footnote_referencelabel="b"/><textxml:space="preserve">.</text></paragraph></block_quote><footnote_definitionlabel="a"><paragraph><textxml:space="preserve">Inside a block quote.</text></paragraph></footnote_definition><footnote_definitionlabel="b"><paragraph><textxml:space="preserve">Inside a footnote definition.</text></paragraph></footnote_definition></document>
If more than one footnote definition has the same label, the first one in the document is used, and the rest are ignored:
<p>A<supclass="footnote-ref"><ahref="#fn-a"id="fnref-a"data-footnote-ref>1</a></sup>.</p><sectionclass="footnotes"data-footnotes><ol><liid="fn-a"><p>First. <ahref="#fnref-a"class="footnote-backref"data-footnote-backrefdata-footnote-backref-idx="1"aria-label="Back to reference 1">↩</a></p></li></ol></section>
A[^a].
[^a]:
First.
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><textxml:space="preserve">A</text><footnote_referencelabel="a"/><textxml:space="preserve">.</text></paragraph><footnote_definitionlabel="a"><paragraph><textxml:space="preserve">First.</text></paragraph></footnote_definition></document>
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><textxml:space="preserve">A[^a] and B[^</text><emph><textxml:space="preserve">b</text></emph><textxml:space="preserve">].</text></paragraph></document>
A footnote reference may appear anywhere inline content may, such as in a heading or in emphasis:
<h1>Title<supclass="footnote-ref"><ahref="#fn-a"id="fnref-a"data-footnote-ref>1</a></sup></h1><p><em>Emphasis<supclass="footnote-ref"><ahref="#fn-a"id="fnref-a-2"data-footnote-ref>1</a></sup></em></p><sectionclass="footnotes"data-footnotes><ol><liid="fn-a"><p>Note. <ahref="#fnref-a"class="footnote-backref"data-footnote-backrefdata-footnote-backref-idx="1"aria-label="Back to reference 1">↩</a><ahref="#fnref-a-2"class="footnote-backref"data-footnote-backrefdata-footnote-backref-idx="1-2"aria-label="Back to reference 1-2">↩<supclass="footnote-ref">2</sup></a></p></li></ol></section>
#Title[^a]*Emphasis[^a]*[^a]:
Note.
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><headinglevel="1"><textxml:space="preserve">Title</text><footnote_referencelabel="a"/></heading><paragraph><emph><textxml:space="preserve">Emphasis</text><footnote_referencelabel="a"/></emph></paragraph><footnote_definitionlabel="a"><paragraph><textxml:space="preserve">Note.</text></paragraph></footnote_definition></document>
An inline link takes precedence over a footnote reference:
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><textxml:space="preserve">A</text><linkdestination="/url"title=""><textxml:space="preserve">^a</text></link><textxml:space="preserve">.</text></paragraph></document>
Numbering
Comrak numbers footnotes in reading order. It reads the document first, skipping footnote definitions, and then reads the content of each numbered footnote in turn. Each footnote gets the next number when Comrak first reads a reference to it, and further references use the same number:
<p>A<supclass="footnote-ref"><ahref="#fn-b"id="fnref-b"data-footnote-ref>1</a></sup>, B<supclass="footnote-ref"><ahref="#fn-a"id="fnref-a"data-footnote-ref>2</a></sup>, and C<supclass="footnote-ref"><ahref="#fn-b"id="fnref-b-2"data-footnote-ref>1</a></sup>.</p><sectionclass="footnotes"data-footnotes><ol><liid="fn-b"><p>Beta. <ahref="#fnref-b"class="footnote-backref"data-footnote-backrefdata-footnote-backref-idx="1"aria-label="Back to reference 1">↩</a><ahref="#fnref-b-2"class="footnote-backref"data-footnote-backrefdata-footnote-backref-idx="1-2"aria-label="Back to reference 1-2">↩<supclass="footnote-ref">2</sup></a></p></li><liid="fn-a"><p>Alpha. <ahref="#fnref-a"class="footnote-backref"data-footnote-backrefdata-footnote-backref-idx="2"aria-label="Back to reference 2">↩</a></p></li></ol></section>
A[^b], B[^a], and C[^b].
[^b]:
Beta.
[^a]:
Alpha.
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><textxml:space="preserve">A</text><footnote_referencelabel="b"/><textxml:space="preserve">, B</text><footnote_referencelabel="a"/><textxml:space="preserve">, and C</text><footnote_referencelabel="b"/><textxml:space="preserve">.</text></paragraph><footnote_definitionlabel="b"><paragraph><textxml:space="preserve">Beta.</text></paragraph></footnote_definition><footnote_definitionlabel="a"><paragraph><textxml:space="preserve">Alpha.</text></paragraph></footnote_definition></document>
A footnote first referred to from another footnote comes after those referred to from the text:
<p>A<supclass="footnote-ref"><ahref="#fn-a"id="fnref-a"data-footnote-ref>1</a></sup> and C<supclass="footnote-ref"><ahref="#fn-c"id="fnref-c"data-footnote-ref>2</a></sup>.</p><sectionclass="footnotes"data-footnotes><ol><liid="fn-a"><p>See B<supclass="footnote-ref"><ahref="#fn-b"id="fnref-b"data-footnote-ref>3</a></sup>. <ahref="#fnref-a"class="footnote-backref"data-footnote-backrefdata-footnote-backref-idx="1"aria-label="Back to reference 1">↩</a></p></li><liid="fn-c"><p>Gamma. <ahref="#fnref-c"class="footnote-backref"data-footnote-backrefdata-footnote-backref-idx="2"aria-label="Back to reference 2">↩</a></p></li><liid="fn-b"><p>Beta. <ahref="#fnref-b"class="footnote-backref"data-footnote-backrefdata-footnote-backref-idx="3"aria-label="Back to reference 3">↩</a></p></li></ol></section>
A[^a] and C[^c].
[^a]:
See B[^b].
[^c]:
Gamma.
[^b]:
Beta.
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><textxml:space="preserve">A</text><footnote_referencelabel="a"/><textxml:space="preserve"> and C</text><footnote_referencelabel="c"/><textxml:space="preserve">.</text></paragraph><footnote_definitionlabel="a"><paragraph><textxml:space="preserve">See B</text><footnote_referencelabel="b"/><textxml:space="preserve">.</text></paragraph></footnote_definition><footnote_definitionlabel="c"><paragraph><textxml:space="preserve">Gamma.</text></paragraph></footnote_definition><footnote_definitionlabel="b"><paragraph><textxml:space="preserve">Beta.</text></paragraph></footnote_definition></document>
Where the definitions are located in the document doesn’t matter:
<p>A<supclass="footnote-ref"><ahref="#fn-a"id="fnref-a"data-footnote-ref>1</a></sup>.</p><sectionclass="footnotes"data-footnotes><ol><liid="fn-a"><p>See B<supclass="footnote-ref"><ahref="#fn-b"id="fnref-b"data-footnote-ref>2</a></sup>. <ahref="#fnref-a"class="footnote-backref"data-footnote-backrefdata-footnote-backref-idx="1"aria-label="Back to reference 1">↩</a></p></li><liid="fn-b"><p>Beta. <ahref="#fnref-b"class="footnote-backref"data-footnote-backrefdata-footnote-backref-idx="2"aria-label="Back to reference 2">↩</a></p></li></ol></section>
A[^a].
[^a]:
See B[^b].
[^b]:
Beta.
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><textxml:space="preserve">A</text><footnote_referencelabel="a"/><textxml:space="preserve">.</text></paragraph><footnote_definitionlabel="a"><paragraph><textxml:space="preserve">See B</text><footnote_referencelabel="b"/><textxml:space="preserve">.</text></paragraph></footnote_definition><footnote_definitionlabel="b"><paragraph><textxml:space="preserve">Beta.</text></paragraph></footnote_definition></document>
The footnotes at the end of the document are those with a number. A footnote definition that isn’t referred to, either from the text or from another numbered footnote, is dropped:
<p>A<supclass="footnote-ref"><ahref="#fn-c"id="fnref-c"data-footnote-ref>1</a></sup>.</p><sectionclass="footnotes"data-footnotes><ol><liid="fn-c"><p>Gamma. <ahref="#fnref-c"class="footnote-backref"data-footnote-backrefdata-footnote-backref-idx="1"aria-label="Back to reference 1">↩</a></p></li></ol></section>
A[^c].
[^c]:
Gamma.
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><textxml:space="preserve">A</text><footnote_referencelabel="c"/><textxml:space="preserve">.</text></paragraph><footnote_definitionlabel="c"><paragraph><textxml:space="preserve">Gamma.</text></paragraph></footnote_definition></document>
Output
HTML output renders a footnote reference as a <sup> element with the class footnote-ref. It contains a link to the footnote, whose text is the footnote’s number. The link’s id is fnref- followed by the label, with -2, -3, and so on added for the second and later references to the same footnote.
The footnotes follow the rest of the document, in a <section> element with the class footnotes that contains an <ol> list. Each footnote is an <li> element whose id is fn- followed by the label. At the end of each footnote are backlinks, one for each reference to it. The backlinks go inside the footnote’s last paragraph if the footnote ends with a paragraph, and otherwise after its last block:
<p>A<supclass="footnote-ref"><ahref="#fn-a"id="fnref-a"data-footnote-ref>1</a></sup> and B<supclass="footnote-ref"><ahref="#fn-a"id="fnref-a-2"data-footnote-ref>1</a></sup>.</p><sectionclass="footnotes"data-footnotes><ol><liid="fn-a"><p>Ends with code.</p><preclass="syntax-highlighting"><code><spanclass="text plain">code
</span></code></pre><ahref="#fnref-a"class="footnote-backref"data-footnote-backrefdata-footnote-backref-idx="1"aria-label="Back to reference 1">↩</a><ahref="#fnref-a-2"class="footnote-backref"data-footnote-backrefdata-footnote-backref-idx="1-2"aria-label="Back to reference 1-2">↩<supclass="footnote-ref">2</sup></a></li></ol></section>
A[^a] and B[^a].
[^a]:
Ends with code.
code
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><textxml:space="preserve">A</text><footnote_referencelabel="a"/><textxml:space="preserve"> and B</text><footnote_referencelabel="a"/><textxml:space="preserve">.</text></paragraph><footnote_definitionlabel="a"><paragraph><textxml:space="preserve">Ends with code.</text></paragraph><code_blockxml:space="preserve">code
</code_block></footnote_definition></document>
Comrak percent-encodes labels in href and id attributes:
<p>A<supclass="footnote-ref"><ahref="#fn-%C3%BCber"id="fnref-%C3%BCber"data-footnote-ref>1</a></sup> and B<supclass="footnote-ref"><ahref="#fn-%3Cb%3E"id="fnref-%3Cb%3E"data-footnote-ref>2</a></sup>.</p><sectionclass="footnotes"data-footnotes><ol><liid="fn-%C3%BCber"><p>Umlaut. <ahref="#fnref-%C3%BCber"class="footnote-backref"data-footnote-backrefdata-footnote-backref-idx="1"aria-label="Back to reference 1">↩</a></p></li><liid="fn-%3Cb%3E"><p>Angle brackets. <ahref="#fnref-%3Cb%3E"class="footnote-backref"data-footnote-backrefdata-footnote-backref-idx="2"aria-label="Back to reference 2">↩</a></p></li></ol></section>
A[^über] and B[^<b>].
[^über]:
Umlaut.
[^<b>]:
Angle brackets.
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><textxml:space="preserve">A</text><footnote_referencelabel="über"/><textxml:space="preserve"> and B</text><footnote_referencelabel="<b>"/><textxml:space="preserve">.</text></paragraph><footnote_definitionlabel="über"><paragraph><textxml:space="preserve">Umlaut.</text></paragraph></footnote_definition><footnote_definitionlabel="<b>"><paragraph><textxml:space="preserve">Angle brackets.</text></paragraph></footnote_definition></document>
CommonMark output writes each footnote reference with its definition’s label, and writes the numbered footnote definitions at the end of the document, in number order. Each definition’s content goes on the lines after its label, indented by four spaces.
In XML output, a footnote reference is a footnote_reference element, and a footnote definition is a footnote_definition element. Both have a label attribute. The footnote definitions come at the end of the document, in number order.
Comrak moves numbered footnote definitions to the end of the document, in number order, and removes the rest. With parse.leave_footnote_definitions, every footnote definition stays where it is in the document, including those that would otherwise be dropped. The option has no command-line flag yet.
Footnote references and definitions have source positions:
<pdata-sourcepos="1:1-1:6">A<supdata-sourcepos="1:2-1:5"class="footnote-ref"><ahref="#fn-a"id="fnref-a"data-footnote-ref>1</a></sup>.</p><sectiondata-sourcepos="3:1-3:11"class="footnotes"data-footnotes><ol><lidata-sourcepos="3:1-3:11"id="fn-a"><pdata-sourcepos="3:7-3:11">Note. <ahref="#fnref-a"class="footnote-backref"data-footnote-backrefdata-footnote-backref-idx="1"aria-label="Back to reference 1">↩</a></p></li></ol></section>
A[^a].
[^a]:
Note.
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentsourcepos="1:1-3:11"xmlns="http://commonmark.org/xml/1.0"><paragraphsourcepos="1:1-1:6"><textsourcepos="1:1-1:1"xml:space="preserve">A</text><footnote_referencesourcepos="1:2-1:5"label="a"/><textsourcepos="1:6-1:6"xml:space="preserve">.</text></paragraph><footnote_definitionsourcepos="3:1-3:11"label="a"><paragraphsourcepos="3:7-3:11"><textsourcepos="3:7-3:11"xml:space="preserve">Note.</text></paragraph></footnote_definition></document>
Interactions
--gfm doesn’t enable footnotes. Without the extension, what looks like a footnote definition forms a link reference definition instead if its content is a single word, and what looks like a footnote reference links to it:
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><textxml:space="preserve">A</text><linkdestination="Alpha."title=""><textxml:space="preserve">^a</text></link><textxml:space="preserve">.</text></paragraph></document>
With inline footnotes, inline footnotes and other footnotes share one sequence:
<p>A<supclass="footnote-ref"><ahref="#fn-__inline_1"id="fnref-__inline_1"data-footnote-ref>1</a></sup> and B<supclass="footnote-ref"><ahref="#fn-b"id="fnref-b"data-footnote-ref>2</a></sup>.</p><sectionclass="footnotes"data-footnotes><ol><liid="fn-__inline_1"><p>Inline. <ahref="#fnref-__inline_1"class="footnote-backref"data-footnote-backrefdata-footnote-backref-idx="1"aria-label="Back to reference 1">↩</a></p></li><liid="fn-b"><p>Labelled. <ahref="#fnref-b"class="footnote-backref"data-footnote-backrefdata-footnote-backref-idx="2"aria-label="Back to reference 2">↩</a></p></li></ol></section>
A[^__inline_1] and B[^b].
[^__inline_1]:
Inline.
[^b]:
Labelled.
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><textxml:space="preserve">A</text><footnote_referencelabel="__inline_1"/><textxml:space="preserve"> and B</text><footnote_referencelabel="b"/><textxml:space="preserve">.</text></paragraph><footnote_definitionlabel="__inline_1"><paragraph><textxml:space="preserve">Inline.</text></paragraph></footnote_definition><footnote_definitionlabel="b"><paragraph><textxml:space="preserve">Labelled.</text></paragraph></footnote_definition></document>
With superscript, a footnote reference’s ^ doesn’t begin superscript:
<p>Here is a footnote reference.<supclass="footnote-ref"><ahref="#fn-1"id="fnref-1"data-footnote-ref>1</a></sup></p><p>Here is a longer footnote reference.<supclass="footnote-ref"><ahref="#fn-ref"id="fnref-ref"data-footnote-ref>2</a></sup></p><p>e = mc<sup>2</sup>.</p><sectionclass="footnotes"data-footnotes><ol><liid="fn-1"><p>Here is the footnote. <ahref="#fnref-1"class="footnote-backref"data-footnote-backrefdata-footnote-backref-idx="1"aria-label="Back to reference 1">↩</a></p></li><liid="fn-ref"><p>Here is another footnote. <ahref="#fnref-ref"class="footnote-backref"data-footnote-backrefdata-footnote-backref-idx="2"aria-label="Back to reference 2">↩</a></p></li></ol></section>
Here is a footnote reference.[^1]
Here is a longer footnote reference.[^ref]
e = mc^2^.
[^1]:
Here is the footnote.
[^ref]:
Here is another footnote.
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><textxml:space="preserve">Here is a footnote reference.</text><footnote_referencelabel="1"/></paragraph><paragraph><textxml:space="preserve">Here is a longer footnote reference.</text><footnote_referencelabel="ref"/></paragraph><paragraph><textxml:space="preserve">e = mc</text><superscript><textxml:space="preserve">2</text></superscript><textxml:space="preserve">.</text></paragraph><footnote_definitionlabel="1"><paragraph><textxml:space="preserve">Here is the footnote.</text></paragraph></footnote_definition><footnote_definitionlabel="ref"><paragraph><textxml:space="preserve">Here is another footnote.</text></paragraph></footnote_definition></document>
<p>A footnote in a paragraph<supclass="footnote-ref"><ahref="#fn-1"id="fnref-1"data-footnote-ref>1</a></sup></p><table><thead><tr><th>Column1</th><th>Column2</th></tr></thead><tbody><tr><td>foot <supclass="footnote-ref"><ahref="#fn-1"id="fnref-1-2"data-footnote-ref>1</a></sup></td><td>note</td></tr></tbody></table><sectionclass="footnotes"data-footnotes><ol><liid="fn-1"><p>a footnote <ahref="#fnref-1"class="footnote-backref"data-footnote-backrefdata-footnote-backref-idx="1"aria-label="Back to reference 1">↩</a><ahref="#fnref-1-2"class="footnote-backref"data-footnote-backrefdata-footnote-backref-idx="1-2"aria-label="Back to reference 1-2">↩<supclass="footnote-ref">2</sup></a></p></li></ol></section>
A footnote in a paragraph[^1]
| Column1 | Column2 ||---|---|| foot [^1] | note |[^1]:
a footnote
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><textxml:space="preserve">A footnote in a paragraph</text><footnote_referencelabel="1"/></paragraph><table><table_header><table_cell><textxml:space="preserve">Column1</text></table_cell><table_cell><textxml:space="preserve">Column2</text></table_cell></table_header><table_row><table_cell><textxml:space="preserve">foot </text><footnote_referencelabel="1"/></table_cell><table_cell><textxml:space="preserve">note</text></table_cell></table_row></table><footnote_definitionlabel="1"><paragraph><textxml:space="preserve">a footnote</text></paragraph></footnote_definition></document>
Differences from cmark-gfm
cmark-gfm, the reference implementation of GitHub Flavored Markdown, uses the same footnote design as Comrak. It doesn’t support the inline footnotes or superscript extensions, so those examples aren’t comparable. On every other example above, the two implementations agree on HTML output, except that cmark-gfm:
numbers footnotes in the order their first references appear in the source, including references inside footnote definitions wherever those definitions are, such that a footnote referred to from a definition near the top of the document can come first (example 23);
lists every footnote with a reference anywhere in the document, even one whose only reference is in a footnote definition that’s dropped, such that its backlink leads nowhere (example 24);
outputs the source text of brackets whose label matches no footnote definition, without parsing their content (example 7, example 18, example 35);
ends a footnote definition at a blank line inside a container such as a block quote, or at a line containing only spaces (example 16); and,
gives footnote references and definitions no source position (example 27).
<p>Here is a footnote reference.<supclass="footnote-ref"><ahref="#fn-%F0%9F%98%84ref"id="fnref-%F0%9F%98%84ref"data-footnote-ref>1</a></sup></p><sectionclass="footnotes"data-footnotes><ol><liid="fn-%F0%9F%98%84ref"><p>Here is the footnote. <ahref="#fnref-%F0%9F%98%84ref"class="footnote-backref"data-footnote-backrefdata-footnote-backref-idx="1"aria-label="Back to reference 1">↩</a></p></li></ol></section>
Here is a footnote reference.[^😄ref]
[^😄ref]:
Here is the footnote.
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><textxml:space="preserve">Here is a footnote reference.</text><footnote_referencelabel="😄ref"/></paragraph><footnote_definitionlabel="😄ref"><paragraph><textxml:space="preserve">Here is the footnote.</text></paragraph></footnote_definition></document>
A label that inline parsing splits into several text nodes (#311):
<p>Foo.<supclass="footnote-ref"><ahref="#fn-_ab"id="fnref-_ab"data-footnote-ref>1</a></sup></p><sectionclass="footnotes"data-footnotes><ol><liid="fn-_ab"><p>Here is the footnote. <ahref="#fnref-_ab"class="footnote-backref"data-footnote-backrefdata-footnote-backref-idx="1"aria-label="Back to reference 1">↩</a></p></li></ol></section>
Foo.[^_ab]
[^_ab]:
Here is the footnote.
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><textxml:space="preserve">Foo.</text><footnote_referencelabel="_ab"/></paragraph><footnote_definitionlabel="_ab"><paragraph><textxml:space="preserve">Here is the footnote.</text></paragraph></footnote_definition></document>
An exclamation mark directly before a footnote reference (#43):
<p>Here's my footnote!<supclass="footnote-ref"><ahref="#fn-a"id="fnref-a"data-footnote-ref>1</a></sup></p><sectionclass="footnotes"data-footnotes><ol><liid="fn-a"><p>Yep. <ahref="#fnref-a"class="footnote-backref"data-footnote-backrefdata-footnote-backref-idx="1"aria-label="Back to reference 1">↩</a></p></li></ol></section>
Here's my footnote\![^a]
[^a]:
Yep.
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><textxml:space="preserve">Here's my footnote!</text><footnote_referencelabel="a"/></paragraph><footnote_definitionlabel="a"><paragraph><textxml:space="preserve">Yep.</text></paragraph></footnote_definition></document>
Footnote-like brackets with emphasis and strikethrough delimiters, and no footnote definitions (cmark-gfm d3a819c):
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><textxml:space="preserve">|Tot.....[^</text><emph><textxml:space="preserve">a</text></emph><textxml:space="preserve">]|</text></paragraph><paragraph><textxml:space="preserve">[^</text><strikethrough><textxml:space="preserve">is</text></strikethrough><textxml:space="preserve">1]</text></paragraph></document>
A document combining several of the cases above, from Comrak’s original footnote tests:
Here is a[^nowhere] footnote reference,[^1] and another.[^longnote]
This is another note.[^note] And footnote[^longnote] is referenced again.
[^note]:Hi.[^1]:Hereis the footnote.[^longnote]:Here'sone with multiple blocks. Subsequent paragraphs are indented.
code
This is regular content.
[^unused]:Thisis not used.
Here is a[^nowhere] footnote reference,1 and another.2
This is another note.3 And footnote2 is referenced again.
<p>Here is a[^nowhere] footnote reference,<supclass="footnote-ref"><ahref="#fn-1"id="fnref-1"data-footnote-ref>1</a></sup> and another.<supclass="footnote-ref"><ahref="#fn-longnote"id="fnref-longnote"data-footnote-ref>2</a></sup></p><p>This is another note.<supclass="footnote-ref"><ahref="#fn-note"id="fnref-note"data-footnote-ref>3</a></sup> And footnote<supclass="footnote-ref"><ahref="#fn-longnote"id="fnref-longnote-2"data-footnote-ref>2</a></sup> is referenced again.</p><p>This is regular content.</p><sectionclass="footnotes"data-footnotes><ol><liid="fn-1"><p>Here is the footnote. <ahref="#fnref-1"class="footnote-backref"data-footnote-backrefdata-footnote-backref-idx="1"aria-label="Back to reference 1">↩</a></p></li><liid="fn-longnote"><p>Here's one with multiple blocks.</p><p>Subsequent paragraphs are indented.</p><preclass="syntax-highlighting"><code><spanclass="text plain">code
</span></code></pre><ahref="#fnref-longnote"class="footnote-backref"data-footnote-backrefdata-footnote-backref-idx="2"aria-label="Back to reference 2">↩</a><ahref="#fnref-longnote-2"class="footnote-backref"data-footnote-backrefdata-footnote-backref-idx="2-2"aria-label="Back to reference 2-2">↩<supclass="footnote-ref">2</sup></a></li><liid="fn-note"><p>Hi. <ahref="#fnref-note"class="footnote-backref"data-footnote-backrefdata-footnote-backref-idx="3"aria-label="Back to reference 3">↩</a></p></li></ol></section>
Here is a\[^nowhere\] footnote reference,[^1] and another.[^longnote]
This is another note.[^note] And footnote[^longnote] is referenced again.
This is regular content.
[^1]:
Here is the footnote.
[^longnote]:
Here's one with multiple blocks.
Subsequent paragraphs are indented.
code
[^note]:
Hi.
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><textxml:space="preserve">Here is a[^nowhere] footnote reference,</text><footnote_referencelabel="1"/><textxml:space="preserve"> and another.</text><footnote_referencelabel="longnote"/></paragraph><paragraph><textxml:space="preserve">This is another note.</text><footnote_referencelabel="note"/><textxml:space="preserve"> And footnote</text><footnote_referencelabel="longnote"/><textxml:space="preserve"> is referenced again.</text></paragraph><paragraph><textxml:space="preserve">This is regular content.</text></paragraph><footnote_definitionlabel="1"><paragraph><textxml:space="preserve">Here is the footnote.</text></paragraph></footnote_definition><footnote_definitionlabel="longnote"><paragraph><textxml:space="preserve">Here's one with multiple blocks.</text></paragraph><paragraph><textxml:space="preserve">Subsequent paragraphs are indented.</text></paragraph><code_blockxml:space="preserve">code
</code_block></footnote_definition><footnote_definitionlabel="note"><paragraph><textxml:space="preserve">Hi.</text></paragraph></footnote_definition></document>