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 for general extension usage, specify markdown.extensions.toc as the name of the extension.

See the Library Reference 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).