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