| 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 (¶ or "`¶`") 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 |
``` |