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]`.

    If a `marker` is not found in the document, then the Table of Contents is
    available as an attribute 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 one argument which contains the
    text content of the header and 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).