/usr/share/doc/python-markdown-doc/docs/extensions/toc.txt is in python-markdown-doc 2.6.9-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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 "`-`".
|