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:

    <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>

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' `<div>`. 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).