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
------
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:
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]`.
Regardless of whether a `marker` is found in the document, the Table of Contents is
also available as an attribute (`toc`) of the Markdown class. This allows one to insert
the Table of Contents elsewhere in their page template. For example:
>>> text = '''
# Header 1
## Header 2
'''
>>> md = markdown.Markdown(extensions=['markdown.extensions.toc'])
>>> html = md.convert(text)
>>> render_some_template(context={'body': html, 'toc': md.toc})
* **`slugify`**:
Callable to generate anchors based on header text. Defaults to a built in
`slugify` method. The callable must accept two arguments, the first
contains the text content of the header and the second contains the
separator. It should then return a string which will be used as the anchor
text.
* **`title`**:
Title to insert in the Table of Contents' ``. Defaults to `None`.
* **`anchorlink`**:
Setting to `True` will cause the headers link to themselves. Default is
`False`.
* **`permalink`**:
Set to `True` to have this extension generate a Sphinx-style permanent links
near the headers (for use with Sphinx stylesheets).