Footnotes

A footnote is a small note attached to a word: the text carries a short reference such as [fn:N], and the note itself, the definition, lives somewhere else, usually in a * Footnotes heading at the end of the file. In export, references become numbers (superscripts in HTML) and the definitions are printed at the end of the document.

This file teaches the four kinds of footnotes, how to jump between a reference and its definition, how to insert new footnotes, and how to sort, renumber, normalize and delete them.

• The file starts folded (#+STARTUP: overview). Put the cursor on a heading and press <Tab> to open it; <S-Tab> cycles the whole buffer.
• <prefix> means your org prefix, <leader>o by default.
• u undoes any edit; git checkout examples/14-footnotes.org restores the file.
• g? lists every key of the buffer.
• Lines starting with Try: are exercises, Expect: says what you should see. Lines starting with =# = are Org comments: they explain the example next to them and are never exported.

Start Neovim from the repository root with the bundled init file:

nvim -u examples/minimal_init.lua examples/14-footnotes.org

In the explanations, N, NAME and TEXT stand for a number, a name and some text. (Sorting, renumbering and normalizing act on a whole buffer, so those exercises happen in small sandboxes, explained in The sandboxes, and never touch the rest of this file.)

A definition is a line that starts, in the very first column, with the label in brackets: [fn:N] or [fn:NAME], then the text. It goes on until the next definition, the next heading, or two blank lines in a row. A label may be referenced as many times as you like.

Here is a paragraph using all four kinds. The definitions of the first two are in the "Footnotes" heading near the end of this file.

Org mode was created by Carsten Dominik¹ and is part of GNU Emacs². Its files are plain text³, so org.nvim can read them too⁴.

The classic footnote: a number in the text, the definition elsewhere.

The first Org release was in 2003⁵. It now ships with Emacs and has its own website⁶.

We said 2003 above; see again the note on the release year⁵.

Try: put the cursor anywhere on [fn:2] in the first line of the example and press <CR>.

Expect: the cursor jumps to the definition line that starts with [fn:2] in the "Footnotes" heading, which reads "The first version, 4.x, appeared in 2003." (The Footnotes heading unfolds as needed.)

Try: now, with the cursor on that [fn:2] at the start of the definition, press <CR> again.

Expect: the cursor is back on the first reference to [fn:2], in "The first Org release was in 2003". A definition always jumps back to the first reference, even if you came from the second.

Try: on [fn:3] press <C-c><C-c>, then <C-o>.

Expect: <C-c><C-c> jumps to "orgmode.org"; <C-o> (the jumplist) brings you back to the reference.

A name is easier to remember than a number, and it never needs renumbering. Names use letters, digits, - and _.

Tables in Org are also spreadsheets⁷, and source blocks can be executed⁸. More about tables: see the note again⁷.

Try: press <CR> on [fn:babel-intro], and <CR> again on the definition.

Expect: first the definition "Babel runs source blocks …" in the Footnotes heading, then back here.

This heading has an ID property: the file 13-links.org links to it with an id: link, see An ID in another file.

An inline footnote carries its own text. There is no separate definition, so there is nothing to jump to: <CR> shows the text in the message area instead.

Neovim started in 2014⁹ and uses Lua for its configuration¹⁰.

Try: press <CR> on the first inline footnote above.

Expect: the message Inline footnote: As a fork of Vim. (the text after the second colon, including its leading space).

A named inline footnote defines its text in place and gives it a name, so other places can refer to it with the short form [fn:NAME].

Vim was released in 1991¹¹. Neovim inherits that heritage¹¹.

Try: press <CR> on [fn:vim-origin] at the end of the second line.

Expect: the cursor jumps to the named inline footnote in the first line (it is the definition of vim-origin).

Try: press <CR> on the named inline footnote itself (on the word "vim-origin" in the first line).

Expect: the cursor jumps to the short reference [fn:vim-origin] on the next line, the first other place using that name.

A definition can have several paragraphs and even lists: it ends only at the next definition, the next heading, or two blank lines in a row. See the definition of this footnote¹² in the Footnotes heading: it has two paragraphs and a list.

Try: press <CR> on [fn:long] and look at the definition.

Expect: the definition starts with "This definition has more than one paragraph." and goes on with a second paragraph and a list, all part of the same footnote.

<prefix>if (C-c C-x f), when the cursor is not on a footnote, inserts a new one:

1. The reference is inserted after the character under the cursor (so put the cursor on the last letter of a word).
2. The label is the first number not used anywhere in the file.
3. An empty definition with the same label is added as the first entry of the "Footnotes" heading (the heading is created at the end of the file when it is missing).
4. The cursor moves to that definition, in Insert mode, ready for you to type the note. <C-o> in Normal mode brings you back.

Try: put the cursor on the final "s" of "footnotes" at the end of the sentence below, and press <prefix>if. Type My first note. and press <Esc>.

This sentence needs more footnotes

Expect: the sentence ends with "more footnotes" and a new reference with the label fn:4 (4, because 1, 2 and 3 are already used in this file), and the Footnotes heading now starts with the definition of fn:4, "My first note.". Press <C-o> to go back to the sentence; <CR> on the new reference goes to the definition again.

Try: go back to the sentence, put the cursor on the "s" at the end of "This", and press <prefix>if again, then <Esc>.

Expect: the sentence starts with "This" and a reference labeled fn:5, and the Footnotes heading now starts with an empty definition of fn:5, above the one of fn:4: new definitions always go first. (u a few times undoes both exercises.)

Sorting, renumbering, normalizing and the footnote options act on a whole buffer. To try them without touching this file, each exercise below is an Org snippet in a #+begin_src org block. Put the cursor inside the block and press <prefix>' (C-c '): the snippet opens in its own Org buffer, where every footnote key works. When you are done:

• <C-c>' (or :w then :q) writes the snippet back into the block, or
• :q! throws your changes away.

Inside the blocks, a heading is written ,* Heading (the comma protects it, Org removes it in the edit buffer).

Try: put the cursor on the line Nothing to see here. below and press <prefix>', then :q!.

Nothing to see here.

Expect: a window with the single line "Nothing to see here." (without the two spaces of indentation); :q! closes it and nothing changes.

With a count, <prefix>if (4<prefix>if, Emacs C-u C-c C-x f) opens the footnote menu:

Sorting and normalizing rebuild the Footnotes heading at the end of the buffer, with a blank line before each definition.

Four options change how <prefix>if creates footnotes. Each can be set in your config or, for one file, with a #+STARTUP: word:

• fnauto / fnplain: numbers (the default); fnprompt: ask for a label; fnconfirm: ask, offering the next number; fnanon: anonymous inline footnotes.
• fnlocal: no Footnotes heading, definitions go at the end of the current section.
• fninline: the new footnote is [fn:N: ], typed in place.
• fnadjust: renumber and sort after every insertion or deletion.

In the config, footnote_auto_label is true (numbers), false (ask), "confirm", "random" or "anonymous"; footnote_section is a heading title ("Footnotes") or false; footnote_auto_adjust is true, "sort", "renumber" or false.

The sandboxes below start with a #+STARTUP: line, which applies to the edit buffer only.

• :Org lint checks footnotes: a reference without a definition (undefined-footnote-reference), a definition nobody refers to (unreferenced-footnote-definition), two definitions with the same label (duplicate-footnote-definition), and anything that is not a definition inside the Footnotes heading (extraneous-element-in-footnote-section).
• In export the references are numbered in order of appearance and the definitions are printed at the end; the Footnotes heading itself is not exported. export.with_footnotes (or #+OPTIONS: f:nil) turns footnotes off.

Try: run :Org lint in this file.

Expect: one entry in the location list, for the reference [fn:sky] in "A reference without a definition": "undefined-footnote-reference: Missing definition for footnote [sky]" (unless you already created its definition in that exercise).

:h org-footnotes

the syntax, the keys and every option

:h org-babel-edit-special

<prefix>' on footnotes and blocks

:h org-lint

the footnote checks

19-export.org

how footnotes are exported

13-links.org

links, another way to point somewhere else