1title: Footnotes Extension 2 3Footnotes 4========= 5 6Summary 7------- 8 9The Footnotes extension adds syntax for defining footnotes in Markdown 10documents. 11 12This extension is included in the standard Markdown library. 13 14Syntax 15------ 16 17Python-Markdown's Footnote syntax follows the generally accepted syntax of the 18Markdown community at large and almost exactly matches [PHP Markdown Extra][]'s 19implementation of footnotes. The only differences involve a few subtleties in 20the output. 21 22[PHP Markdown Extra]: http://michelf.com/projects/php-markdown/extra/#footnotes 23 24Example: 25 26```md 27Footnotes[^1] have a label[^@#$%] and the footnote's content. 28 29[^1]: This is a footnote content. 30[^@#$%]: A footnote on the label: "@#$%". 31``` 32 33A footnote label must start with a caret `^` and may contain any inline text 34(including spaces) between a set of square brackets `[]`. Only the first 35caret has any special meaning. 36 37A footnote content must start with the label followed by a colon and at least 38one space. The label used to define the content must exactly match the label used 39in the body (including capitalization and white space). The content would then 40follow the label either on the same line or on the next line. The content may 41contain multiple lines, paragraphs, code blocks, blockquotes and most any other 42markdown syntax. The additional lines must be indented one level (four spaces or 43one tab). 44 45When working with multiple blocks, it may be helpful to start the content on a 46separate line from the label which defines the content. This way the entire block 47is indented consistently and any errors are more easily discernible by the author. 48 49```md 50[^1]: 51 The first paragraph of the definition. 52 53 Paragraph two of the definition. 54 55 > A blockquote with 56 > multiple lines. 57 58 a code block 59 60 A final paragraph. 61``` 62 63Usage 64----- 65 66See [Extensions](index.md) for general extension usage. Use `footnotes` as the 67name of the extension. 68 69See the [Library Reference](../reference.md#extensions) for information about 70configuring extensions. 71 72The following options are provided to configure the output: 73 74* **`PLACE_MARKER`**: 75 A text string used to mark the position where the footnotes are rendered. 76 Defaults to `///Footnotes Go Here///`. 77 78 If the place marker text is not found in the document, the footnote 79 definitions are placed at the end of the resulting HTML document. 80 81* **`UNIQUE_IDS`**: 82 Whether to avoid collisions across multiple calls to `reset()`. Defaults to 83 `False`. 84 85* **`BACKLINK_TEXT`**: 86 The text string that links from the footnote definition back to the position 87 in the document. Defaults to `↩`. 88 89* **`SUPERSCRIPT_TEXT`**: 90 The text string that links from the position in the document to the footnote 91 definition. Defaults to `{}`, i.e. only the footnote's number. 92 93* **`BACKLINK_TITLE`**: 94 The text string for the `title` HTML attribute of the footnote definition link. 95 The placeholder `{}` will be replaced by the footnote number. Defaults to 96 `Jump back to footnote {} in the text`. 97 98* **`SEPARATOR`**: 99 The text string used to set the footnote separator. Defaults to `:`. 100 101A trivial example: 102 103```python 104markdown.markdown(some_text, extensions=['footnotes']) 105``` 106 107Resetting Instance State 108----- 109 110Footnote definitions are stored within the `markdown.Markdown` class instance between 111multiple runs of the class. This allows footnotes from all runs to be included in 112output, with links and references that are unique, even though the class has been 113called multiple times. 114 115However, if needed, the definitions can be cleared between runs by calling `reset`. 116 117For instance, the home page of a blog might include the content from multiple documents. 118By not calling `reset`, all of the footnotes will be rendered, and they will all have 119unique links and references. 120 121On the other hand, individual blog post pages might need the content from only one 122document, and should have footnotes pertaining only to that page. By calling `reset` 123between runs, the footnote definitions from the first document will be cleared before 124the second document is rendered. 125 126An example of calling `reset`: 127 128```python 129md = markdown.Markdown(extensions=['footnotes']) 130html1 = md.convert(text_with_footnote) 131md.reset() 132html2 = md.convert(text_without_footnote) 133``` 134