This syntax feature is not part of the original Markdown syntax. The idea and syntax comes from the PHP Markdown Extra package.
Footnotes in kramdown are similar to reference style links and link definitions. You need to place the footnote marker in the correct position in the text and the actual footnote content can be defined anywhere in the document.
More exactly, a footnote marker can be created by placing the footnote name in square brackets. The footnote name has to start with a caret (^), followed by a word character or a digit and then optionally followed by other word characters, digits or dashes. For example:
This is some text.[^1]. Other text.[^footnote].
Footnote markers with the same name will link to the same footnote definition. The actual naming of a footnote does not matter since the numbering of footnotes is controlled via the position of the footnote markers in the document (the first found footnote marker will get the number 1, the second new footnote marker the number 2 and so on). If there is a footnote definition found for the identifier, a footnote will be created. Otherwise the footnote marker is not converted to a footnote link. Also note that all attributes set via a span IAL are ignored for a footnote marker!
A footnote definition is used to define the content of a footnote and has the following structure:
- The footnote name in square brackets, optionally indented up to three spaces,
- then a colon and one or more optional spaces,
- then the text of the footnote
- and optionally more text on the following lines which have to follow the syntax for standard code blocks (the leading four spaces/one tab are naturally stripped from the text)
Footnote definitions are, despite being described here, non-content block-level elements.
The whole footnote content is treated like block-level text and can therefore contain any valid block-level element (also, any block-level element can be the first element). If you want to have a code block as first element, note that all leading spaces/tabs on the first line are stripped away. Here are some example footnote definitions:
[^1]: Some *crazy* footnote definition.
[^footnote]:
> Blockquotes can be in a footnote.
as well as code blocks
or, naturally, simple paragraphs.
[^other-note]: no code block here (spaces are stripped away)
[^codeblock-note]:
this is now a code block (8 spaces indentation)
It does not matter where you put a footnote definition in a kramdown document; the content of all referenced footnote definitions will be placed at the end of the kramdown document. Not referenced footnote definitions are ignored. If more than one footnote definitions have the same footnote name, all footnote definitions but the last are ignored.