Footnotes

You can add footnotes to your document using the footnote macro (footnote:[text]). If you specify a target (footnote:id[text]), you can refer to that footnote from multiple locations in the document. The target becomes the ID of the footnote, which you can use to refer to it (footnote:id[]).

Example 1. Footnote syntax
The hail-and-rainbow protocol can be initiated at five levels:

. doublefootnote:[The double hail-and-rainbow level makes my toes tingle.] (1) (2)
. tertiary
. supernumerary
. supermassive
. apocalyptic

A bold statement!footnote:disclaimer[Opinions are my own.] (3)

Another outrageous statement.footnote:disclaimer[] (4)
1 Insert the footnote macro directly after any punctuation. Note that the footnote macro only uses a single colon (:).
2 Insert the footnote’s content within the square brackets ([]). The text may span several lines.
3 If you plan to reuse a footnote, specify a unique ID in the target position.
4 To reference an existing footnote, you only need to specify the ID of the footnote in the target slot. The text between the square brackets should be empty. If both the ID and text are specified, and the ID has already been defined by an earlier footnote, the text is ignored.
If you find that having to put the footnote macro directly adjacent to a word makes it difficult to read, you can insert an attribute reference in between that resolves to an empty string (e.g., word{empty}footnote:[text]).

The footnotes are numbered consecutively throughout the article.

The results of Example 1 are displayed below.

The hail-and-rainbow protocol can be initiated at five levels

  1. double[1]

  2. tertiary

  3. supernumerary

  4. supermassive

  5. apocalyptic

A bold statement![2]

Another outrageous statement.[2]


1. The double hail-and-rainbow level makes my toes tingle.
2. Opinions are my own.

Just like normal paragraph text, you can use text formatting markup in the text of the footnote.

Externalizing a footnote

Since footnotes are defined using an inline macro, the footnote content must be inserted alongside the text it’s annotating. This requirement can make the text harder to read. You can solve this problem by externalizing your footnotes using document attributes.

When defining a document attribute that holds a footnote, you can name the document attributes whatever you want. A common practice is to name the attribute using the fn- prefix. The name of the attribute can be as verbose (fn-disclaimer) or concise (fn-1) as you prefer.

Here’s the previous example with the footnotes defined in document attributes and inserted using attribute references.

Example 2. Externalized footnote
:fn-hail-and-rainbow: footnote:[The double hail-and-rainbow level makes my toes tingle.]
:fn-disclaimer: footnote:disclaimer[Opinions are my own.]

The hail-and-rainbow protocol can be initiated at five levels:

. double{fn-hail-and-rainbow}
. tertiary
. supernumerary
. supermassive
. apocalyptic

A bold statement!{fn-disclaimer}

Another outrageous statement.{fn-disclaimer}

Notice you still get the benefit of seeing where the footnote is placed without all the noise. And since the footnotes are now defined in the document header, they could be further externalized to an include file.

This approach works since attribute references are expanded before footnotes are parsed. However, this technique does not work if you have text formatting markup in the text of the footnote (e.g., *bold*). That markup will not be interpreted. That’s because the attributes substitution (which replaces attribute references) is applied after the quotes substitution (which interprets text formatting markup). In order to use text formatting markup in the text of the footnote, you need to configure the substitutions on the value of the attribute entry using the pass:[] macro.

The following example demonstrates how to configure the substitutions applied to the text of an externalized footnote so that text formatting markup is honored.

Example 3. Externalized footnote with text formatting
:fn-disclaimer: pass:c,q[footnote:disclaimer[Opinions are _mine_, and mine *alone*.]]

A bold statement!{fn-disclaimer}

Another outrageous statement.{fn-disclaimer}

The c,q target on the pass macro instructs the processor to apply the special characters substitution followed by the quotes substitution. That means the text formatting in the footnote text will already be applied when the footnote is inserted using an attribute reference.

Footnotes in Headings

If you use a footnote in a heading, you’ll likely find that the footnote sequence is wrong. That’s because headings (section titles and discrete headings) get converted out of document order for the purpose of generating IDs and setting up cross references.

To resolve this problem, you must assign an explicit ID and reftext to any heading that contains a footnote. For example:

See <<heading>>.

[[heading,Heading]]
== Headingfootnote:[This is a heading with a footnote]

Not only will this prevent the footnote from being processed out of document order (and thus assigned the wrong number in the sequence), it will also prevent the footnote number from reappearing in the text of an xref.