Debian Codegraph @

docs/extensions/toc.md

raw
1 title: Table of Contents Extension
2
3 Table of Contents
4 =================
5
6 Summary
7 -------
8
9 The Table of Contents extension generates a Table of Contents from a Markdown
10 document and adds it into the resulting HTML document.
11
12 This extension is included in the standard Markdown library.
13
14 Syntax
15 ------
16
17 By default, all headers will automatically have unique `id` attributes
18 generated based upon the text of the header. Note this example, in which all
19 three headers would have the same `id`:
20
21 ```md
22 #Header
23 #Header
24 #Header
25 ```
26
27 Results in:
28
29 ```html
30 <h1 id="header">Header</h1>
31 <h1 id="header_1">Header</h1>
32 <h1 id="header_2">Header</h1>
33 ```
34
35 Place a marker in the document where you would like the Table of Contents to
36 appear. Then, a nested list of all the headers in the document will replace the
37 marker. The marker defaults to `[TOC]` so the following document:
38
39 ```md
40 [TOC]
41
42 # Header 1
43
44 ## Header 2
45 ```
46
47 would generate the following output:
48
49 ```html
50 <div class="toc">
51 <ul>
52 <li>
53 <a href="#header-1">Header 1</a>
54 <ul>
55 <li><a href="#header-2">Header 2</a></li>
56 </ul>
57 </li>
58 </ul>
59 </div>
60 <h1 id="header-1">Header 1</h1>
61 <h2 id="header-2">Header 2</h2>
62 ```
63
64 Regardless of whether a `marker` is found in the document (or disabled), the
65 Table of Contents is available as an attribute (`toc`) on the Markdown class.
66 This allows one to insert the Table of Contents elsewhere in their page
67 template. For example:
68
69 ```pycon
70 >>> md = markdown.Markdown(extensions=['toc'])
71 >>> html = md.convert(text)
72 >>> page = render_some_template(context={'body': html, 'toc': md.toc})
73 ```
74
75 The `toc_tokens` attribute is also available on the Markdown class and contains
76 a nested list of dict objects. For example, the above document would result in
77 the following object at `md.toc_tokens`:
78
79 ```python
80 [
81 {
82 'level': 1,
83 'id': 'header-1',
84 'name': 'Header 1',
85 'html': 'Header 1',
86 'data-toc-label': '',
87 'children': [
88 {'level': 2, 'id': 'header-2', 'name': 'Header 2', 'children':[]}
89 ]
90 }
91 ]
92 ```
93
94 Note that the `level` refers to the `hn` level. In other words, `<h1>` is level
95 `1` and `<h2>` is level `2`, etc. Be aware that improperly nested levels in the
96 input may result in odd nesting of the output.
97
98 `name` is the sanitized value which would also be used as a label for the HTML
99 version of the Table of Contents. `html` contains the fully rendered HTML
100 content of the heading and has not been sanitized in any way. This may be used
101 with your own custom sanitation to create custom table of contents.
102
103 ### Custom Labels
104
105 In most cases, the text label in the Table of Contents should match the text of
106 the header. However, occasionally that is not desirable. In that case, if this
107 extension is used in conjunction with the [Attribute Lists Extension] and a
108 `data-toc-label` attribute is defined on the header, then the contents of that
109 attribute will be used as the text label for the item in the Table of Contents.
110 For example, the following Markdown:
111
112 [Attribute Lists Extension]: attr_list.md
113
114 ```md
115 [TOC]
116
117 # Functions
118
119 ## `markdown.markdown(text [, **kwargs])` { #markdown data-toc-label='markdown.markdown' }
120 ```
121 would generate the following output:
122
123 ```html
124 <div class="toc">
125 <ul>
126 <li>
127 <a href="#functions">Functions</a>
128 <ul>
129 <li><a href="#markdown">markdown.markdown</a></li>
130 </ul>
131 </li>
132 </ul>
133 </div>
134 <h1 id="functions">Functions</h1>
135 <h2 id="markdown"><code>markdown.markdown(text [, **kwargs])</code></h2>
136 ```
137
138 Notice that the text in the Table of Contents is much cleaner and easier to read
139 in the context of a Table of Contents. The `data-toc-label` is not included in
140 the HTML header element. Also note that the ID was manually defined in the
141 attribute list to provide a cleaner URL when linking to the header. If the ID is
142 not manually defined, it is always derived from the text of the header, never
143 from the `data-toc-label` attribute.
144
145 The value of the `data-toc-label` attribute is sanitized and stripped of any HTML
146 tags. However, `toc_tokens` will contain the raw content under
147 `data-toc-label`.
148
149 Usage
150 -----
151
152 See [Extensions](index.md) for general extension usage. Use `toc` as the name
153 of the extension.
154
155 See the [Library Reference](../reference.md#extensions) for information about
156 configuring extensions.
157
158 The following options are provided to configure the output:
159
160 * **`marker`**:
161 Text to find and replace with the Table of Contents. Defaults to `[TOC]`.
162
163 Set to an empty string to disable searching for a marker, which may save
164 some time, especially on long documents.
165
166 * **`title`**:
167 Title to insert in the Table of Contents' `<div>`. Defaults to `None`.
168
169 * **`title_class`**:
170 CSS class used for the title contained in the Table of Contents. Defaults to `toctitle`.
171
172 * **`toc_class`**:
173 CSS class(es) used for the `<div>` containing the Table of Contents. Defaults to `toc`.
174
175 * **`anchorlink`**:
176 Set to `True` to cause all headers to link to themselves. Default is `False`.
177
178 * **`anchorlink_class`**:
179 CSS class(es) used for the link. Defaults to `toclink`.
180
181 * **`permalink`**:
182 Set to `True` or a string to generate permanent links at the end of each header.
183 Useful with Sphinx style sheets.
184
185 When set to `True` the paragraph symbol (&para; or "`&para;`") is used as
186 the link text. When set to a string, the provided string is used as the link
187 text.
188
189 * **`permalink_class`**:
190 CSS class(es) used for the link. Defaults to `headerlink`.
191
192 * **`permalink_title`**:
193 Title attribute of the permanent link. Defaults to `Permanent link`.
194
195 * **`permalink_leading`**:
196 Set to `True` if the extension should generate leading permanent links.
197 Default is `False`.
198
199 Leading permanent links are placed at the start of the header tag,
200 before any header content. The default `permalink` behavior (when
201 `permalink_leading` is unset or set to `False`) creates trailing
202 permanent links, which are placed at the end of the header content.
203
204 * **`baselevel`**:
205 Base level for headers. Defaults to `1`.
206
207 The `baselevel` setting allows the header levels to be automatically
208 adjusted to fit within the hierarchy of your HTML templates. For example,
209 suppose the Markdown text for a page should not contain any headers higher
210 than level 3 (`<h3>`). The following will accomplish that:
211
212 :::pycon
213 >>> text = '''
214 ... #Some Header
215 ... ## Next Level'''
216 >>> from markdown.extensions.toc import TocExtension
217 >>> html = markdown.markdown(text, extensions=[TocExtension(baselevel=3)])
218 >>> print html
219 <h3 id="some_header">Some Header</h3>
220 <h4 id="next_level">Next Level</h4>'
221
222 * **`slugify`**:
223 Callable to generate anchors.
224
225 Default: `markdown.extensions.toc.slugify`
226
227 In order to use a different algorithm to define the id attributes, define and
228 pass in a callable which takes the following two arguments:
229
230 * `value`: The string to slugify.
231 * `separator`: The Word Separator.
232
233 The callable must return a string appropriate for use in HTML `id` attributes.
234
235 An alternate version of the default callable supporting Unicode strings is also
236 provided as `markdown.extensions.toc.slugify_unicode`.
237
238 * **`separator`**:
239 Word separator. Character which replaces white space in id. Defaults to "`-`".
240
241 * **`toc_depth`**
242 Define the range of section levels to include in the Table of Contents.
243 A single integer (`b`) defines the bottom section level (`<h1>..<hb>`) only.
244 A string consisting of two digits separated by a hyphen in between (`"2-5"`),
245 define the top (`t`) and the bottom (`b`) (`<ht>..<hb>`). Defaults to `6` (bottom).
246
247 When used with conjunction with `baselevel`, this parameter will not
248 take the fitted hierarchy from `baselevel` into account. That is, if
249 both `toc_depth` and `baselevel` are `3`, then only the highest level
250 will be present in the table. If you set `baselevel` to `3` and
251 `toc_depth` to `"2-6"`, the *first* headline will be `<h3>` and so still
252 included in the Table of Contents. To exclude this first level, you
253 have to set `toc_depth` to `"4-6"`.
254
255 A trivial example:
256
257 ```python
258 markdown.markdown(some_text, extensions=['toc'])
259 ```