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

Adds a Table of Contents to a Markdown document.

This extension is included with the Markdown library since version 2.0.

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

From the Python interpreter:

    >>> html = markdown.markdown(some_text, extensions=['toc'])

The following options are provided to configure the output:

* **marker**: Text to find and replace with the Table of Contents. Defaults
  to ``[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 TOC ``<div>``. Defaults to ``None``.
* **anchorlink**: Set to ``True`` to have the headers link to themselves. 
  Default is ``False``.
* **permalink**: Set to ``True`` to have this extension generate Sphinx-style
  permanent links near the headers (for use with Sphinx stylesheets).

If a 'marker' is not found in the document, then the toc is available as an
attribute of the Markdown class. This allows one to insert the toc elsewhere 
in their page template. For example:

    >>> text = '''
    # Header 1
    
    ## Header 2
    '''
    >>> md = markdown.Markdown(extensions=['toc'])
    >>> html = md.convert(text)
    >>> render_some_template(context={'body': html, 'toc': md.toc})