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.

Here’s a typical footnote:

Example 1
$ comrak -e footnotes
Hi[^x].

[^x]: A greeting.

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:

Example 2
$ comrak -e footnotes
A[^a.b-c_d] and B[^über].

[^a.b-c_d]: Punctuation.
[^über]: Not ASCII.

A label can’t contain whitespace. Neither of these lines is a footnote reference or a footnote definition:

Example 3
$ comrak -e footnotes
Foo.[^one two]

[^one two]: Here is the footnote.

A label can’t be empty either:

Example 4
$ comrak -e footnotes
Foo.[^]

[^]: Here is the footnote.

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:

Example 5
$ comrak -e footnotes
Here is a footnote reference.[^AB] and [^ab]

[^aB]: Here is the footnote.

Whitespace at either end of the reference’s label is also ignored:

Example 6
$ comrak -e footnotes
A[^a], B[^ a] and C[^a ].

[^a]: Note.

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`:

Example 7
$ comrak -e footnotes
A[^a] and B[^`b`].

[^a]: Plain.
[^`b`]: Backticks.

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:

Example 8
$ comrak -e footnotes
A[^a].

[^a]: First paragraph.

    Second paragraph.

A line with less indentation ends the definition:

Example 9
$ comrak -e footnotes
A[^a].

[^a]: First paragraph.

  Not in the footnote.

A lazy continuation line continues a paragraph as usual:

Example 10
$ comrak -e footnotes
A[^a].

[^a]: First line,
second line.

The content may begin on a later line, and may begin with any kind of block:

Example 11
$ comrak -e footnotes
A[^a] and B[^b].

[^a]:
    On the next line.

[^b]: > A block quote.

A footnote definition may be empty:

Example 12
$ comrak -e footnotes
A[^a].

[^a]:

A footnote definition may interrupt a paragraph:

Example 13
$ comrak -e footnotes
A[^a].
[^a]: Note.

The colon must directly follow the ], but the content needn’t be separated from the colon:

Example 14
$ comrak -e footnotes
A[^a] and B[^b].

[^a] : Not a definition.

[^b]:Note.

Four spaces of indentation begin an indented code block instead:

Example 15
$ comrak -e footnotes
A[^a].

    [^a]: Code.

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:

Example 16
$ comrak -e footnotes
> A[^a] and B[^b].
>
> [^a]: Inside a block quote.
>
>     [^b]: Inside a footnote definition.

If more than one footnote definition has the same label, the first one in the document is used, and the rest are ignored:

Example 17
$ comrak -e footnotes
A[^a].

[^a]: First.

[^a]: Second.

Footnote references

A footnote reference is [^, followed by text that matches the label of a footnote definition, followed by ]. Footnote labels describes how labels match.

Brackets without a matching label are parsed like any other non-footnote Markdown:

Example 18
$ comrak -e footnotes
A[^a] and B[^*b*].

A footnote reference may appear anywhere inline content may, such as in a heading or in emphasis:

Example 19
$ comrak -e footnotes
# Title[^a]

*Emphasis[^a]*

[^a]: Note.

An inline link takes precedence over a footnote reference:

Example 20
$ comrak -e footnotes
A[^a]/url.

[^a]: Note.

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:

Example 21
$ comrak -e footnotes
A[^b], B[^a], and C[^b].

[^a]: Alpha.
[^b]: Beta.

A footnote first referred to from another footnote comes after those referred to from the text:

Example 22
$ comrak -e footnotes
A[^a] and C[^c].

[^a]: See B[^b].
[^b]: Beta.
[^c]: Gamma.

Where the definitions are located in the document doesn’t matter:

Example 23
$ comrak -e footnotes
[^a]: See B[^b].
[^b]: Beta.

A[^a].

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:

Example 24
$ comrak -e footnotes
A[^c].

[^a]: Not referred to.
[^b]: Only referred to from[^a].
[^c]: Gamma.

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:

Example 25
$ comrak -e footnotes
A[^a] and B[^a].

[^a]: Ends with code.

        code

Comrak percent-encodes labels in href and id attributes:

Example 26
$ comrak -e footnotes
A[^über] and B[^<b>].

[^über]: Umlaut.
[^<b>]: Angle brackets.

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.

In the AST, a footnote reference is a NodeValue::FootnoteReference. Its NodeFootnoteReference holds the label, the footnote’s number (ix), and which reference to the footnote this is (ref_num). A footnote definition is a NodeValue::FootnoteDefinition, whose NodeFootnoteDefinition holds the label and the number of references to it (total_references), with the content as its children.

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:

Example 27
$ comrak -e footnotes --sourcepos
A[^a].

[^a]: Note.

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:

Example 28
$ comrak --gfm
A[^a].

[^a]: Alpha.

With inline footnotes, inline footnotes and other footnotes share one sequence:

Example 29
$ comrak -e footnotes -e inline-footnotes
A^[Inline.] and B[^b].

[^b]: Labelled.

With superscript, a footnote reference’s ^ doesn’t begin superscript:

Example 30
$ comrak -e footnotes -e superscript
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.

Footnote references work in table cells:

Example 31
$ comrak -e footnotes -e table
A footnote in a paragraph[^1]

| Column1   | Column2 |
| --------- | ------- |
| foot [^1] | note    |

[^1]: a footnote

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:

cmark-gfm’s XML output doesn’t support footnotes.

Regressions

The following examples guard against regressions.

A label with an emoji (#306):

Example 32
$ comrak -e footnotes
Here is a footnote reference.[^😄ref]

[^😄ref]: Here is the footnote.

A label that inline parsing splits into several text nodes (#311):

Example 33
$ comrak -e footnotes
Foo.[^_ab]

[^_ab]: Here is the footnote.

An exclamation mark directly before a footnote reference (#43):

Example 34
$ comrak -e footnotes
Here's my footnote![^a]

[^a]: Yep.

Footnote-like brackets with emphasis and strikethrough delimiters, and no footnote definitions (cmark-gfm d3a819c):

Example 35
$ comrak -e footnotes -e table -e strikethrough -e autolink
|Tot.....[^_a_]|

[^~~is~~1]

A document combining several of the cases above, from Comrak’s original footnote tests:

Example 36
$ comrak -e footnotes
Here is a[^nowhere] footnote reference,[^1] and another.[^longnote]

This is another note.[^note] And footnote[^longnote] is referenced again.

[^note]: Hi.

[^1]: Here is the footnote.

[^longnote]: Here's one with multiple blocks.

    Subsequent paragraphs are indented.

        code

This is regular content.

[^unused]: This is not used.