1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
|
title: Table of Contents Extension
prev_title: SmartyPants Extension
prev_url: smarty.html
next_title: WikiLinks Extension
next_url: wikilinks.html
Table of Contents
=================
Summary
-------
The Table of Contents extension generates a Table of Contents from a Markdown
document and adds it into the resulting HTML document.
This extension is included in the standard Markdown library.
Syntax
------
By default, all headers will automatically have unique `id` attributes
generated based upon the text of the header. Note this example, in which all
three headers would have the same `id`:
#Header
#Header
#Header
Results in:
<h1 id="header">Header</h1>
<h1 id="header_1">Header</h1>
<h1 id="header_2">Header</h1>
Place a marker in the document where you would like the Table of Contents to
appear. Then, a nested list of all the headers in the document will replace the
marker. The marker defaults to `[TOC]` so the following document:
[TOC]
# Header 1
## Header 2
would generate the following output:
<div class="toc">
<ul>
<li><a href="#header-1">Header 1</a></li>
<ul>
<li><a href="#header-2">Header 2</a></li>
</ul>
</ul>
</div>
<h1 id="header-1">Header 1</h1>
<h1 id="header-2">Header 2</h1>
Regardless of whether a `marker` is found in the document (or disabled), the Table of
Contents is available as an attribute (`toc`) on the Markdown class. This allows
one to insert the Table of Contents elsewhere in their page template. For example:
>>> md = markdown.Markdown(extensions=['markdown.extensions.toc'])
>>> html = md.convert(text)
>>> page = render_some_template(context={'body': html, 'toc': md.toc})
Usage
-----
See [Extensions](index.html) for general extension usage, specify `markdown.extensions.toc`
as the name of the extension.
See the [Library Reference](../reference.html#extensions) for information about
configuring extensions.
The following options are provided to configure the output:
* **`marker`**:
Text to find and replace with the Table of Contents. Defaults to `[TOC]`.
Set to an empty string to disable searching for a marker, which may save some time,
especially on long documents.
* **`title`**:
Title to insert in the Table of Contents' `<div>`. Defaults to `None`.
* **`anchorlink`**:
Set to `True` to cause all headers to link to themselves. Default is `False`.
* **`permalink`**:
Set to `True` or a string to generate permanent links at the end of each header.
Useful with Sphinx style sheets.
When set to `True` the paragraph symbol (¶ or "`¶`") is used as the link
text. When set to a string, the provided string is used as the link text.
* **`baselevel`**:
Base level for headers. Defaults to `1`.
The `baselevel` setting allows the header levels to be automatically adjusted to
fit within the hierarchy of your HTML templates. For example, suppose the
Markdown text for a page should not contain any headers higher than level 3
(`<h3>`). The following will accomplish that:
>>> text = '''
... #Some Header
... ## Next Level'''
>>> from markdown.extensions.toc import TocExtension
>>> html = markdown.markdown(text, extensions=[TocExtension(baselevel=3)])
>>> print html
<h3 id="some_header">Some Header</h3>
<h4 id="next_level">Next Level</h4>'
* **`slugify`**:
Callable to generate anchors.
Default: `markdown.extensions.headerid.slugify`
In order to use a different algorithm to define the id attributes, define and
pass in a callable which takes the following two arguments:
* `value`: The string to slugify.
* `separator`: The Word Separator.
The callable must return a string appropriate for use in HTML `id` attributes.
* **`separator`**:
Word separator. Character which replaces white space in id. Defaults to "`-`".
|
