Debian Codegraph @

docs/extensions/footnotes.md

raw
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 ```