# ‹› `` `markdown.extensions.toc`

Add table of contents support to Python-Markdown.

See the documentation for details.

Classes:

- `TocTreeprocessor` –

  Step through document and build TOC.

- `TocExtension` –

Functions:

- `slugify` –

  Slugify a string, to make it URL friendly.

- `slugify_unicode` –

  Slugify a string, to make it URL friendly while preserving Unicode characters.

- `unique` –

  Ensure id is unique in set of ids. Append ‘_1’, ‘_2’… if not

- `get_name` –

  Get title name.

- `stashedHTML2text` –

  Extract raw HTML from stash, reduce to plain text and swap with placeholder.

- `unescape` –

  Unescape Markdown backslash escaped text.

- `strip_tags` –

  Strip HTML tags and return plain text. Note: HTML entities are unaffected.

- `escape_cdata` –

  Escape character data.

- `run_postprocessors` –

  Run postprocessors from Markdown instance on text.

- `render_inner_html` –

  Fully render inner html of an `etree` element as a string.

- `remove_fnrefs` –

  Remove footnote references from a copy of the element, if any are present.

- `nest_toc_tokens` –

  Given an unsorted list with errors and skips, return a nested one.

## ‹› `` `markdown.extensions.toc.slugify(value: str, separator: str, unicode: bool = False) -> str`

Slugify a string, to make it URL friendly.

## ‹› `` `markdown.extensions.toc.slugify_unicode(value: str, separator: str) -> str`

Slugify a string, to make it URL friendly while preserving Unicode characters.

## ‹› `` `markdown.extensions.toc.unique(id: str, ids: MutableSet[str]) -> str`

Ensure id is unique in set of ids. Append ‘_1’, ‘_2’… if not

## ‹› `` `markdown.extensions.toc.get_name(el: etree.Element) -> str` `deprecated`

Deprecated

Use `render_inner_html` and `striptags` instead.

Get title name.

## ‹› `` `markdown.extensions.toc.stashedHTML2text(text: str, md: Markdown, strip_entities: bool = True) -> str` `deprecated`

Deprecated

Use `run_postprocessors`, `render_inner_html` and/or `striptags` instead.

Extract raw HTML from stash, reduce to plain text and swap with placeholder.

## ‹› `` `markdown.extensions.toc.unescape(text: str) -> str`

Unescape Markdown backslash escaped text.

## ‹› `` `markdown.extensions.toc.strip_tags(text: str) -> str`

Strip HTML tags and return plain text. Note: HTML entities are unaffected.

## ‹› `` `markdown.extensions.toc.escape_cdata(text: str) -> str`

Escape character data.

## ‹› `` `markdown.extensions.toc.run_postprocessors(text: str, md: Markdown) -> str`

Run postprocessors from Markdown instance on text.

## ‹› `` `markdown.extensions.toc.render_inner_html(el: etree.Element, md: Markdown) -> str`

Fully render inner html of an `etree` element as a string.

## ‹› `` `markdown.extensions.toc.remove_fnrefs(root: etree.Element) -> etree.Element`

Remove footnote references from a copy of the element, if any are present.

## ‹› `` `markdown.extensions.toc.nest_toc_tokens(toc_list)`

Given an unsorted list with errors and skips, return a nested one.

    [{'level': 1}, {'level': 2}]
    =>
    [{'level': 1, 'children': [{'level': 2, 'children': []}]}]

A wrong list is also converted:

    [{'level': 2}, {'level': 1}]
    =>
    [{'level': 2, 'children': []}, {'level': 1, 'children': []}]

## ‹› `` `markdown.extensions.toc.TocTreeprocessor(md: Markdown, config: dict[str, Any])`

Bases: `Treeprocessor`

Step through document and build TOC.

Methods:

- `iterparent` –

  Iterator wrapper to get allowed parent and child all at once.

- `replace_marker` –

  Replace marker with elem.

- `set_level` –

  Adjust header level according to base level.

- `build_toc_div` –

  Return a string div given a toc list.

### ‹› `` `markdown.extensions.toc.TocTreeprocessor.iterparent(node: etree.Element) -> Iterator[tuple[etree.Element, etree.Element]]`

Iterator wrapper to get allowed parent and child all at once.

### ‹› `` `markdown.extensions.toc.TocTreeprocessor.replace_marker(root: etree.Element, elem: etree.Element) -> None`

Replace marker with elem.

### ‹› `` `markdown.extensions.toc.TocTreeprocessor.set_level(elem: etree.Element) -> None`

Adjust header level according to base level.

### ‹› `` `markdown.extensions.toc.TocTreeprocessor.build_toc_div(toc_list: list) -> etree.Element`

Return a string div given a toc list.

## ‹› `` `markdown.extensions.toc.TocExtension(**kwargs)`

Bases: `Extension`

Methods:

- `extendMarkdown` –

  Add TOC tree processor to Markdown.

Attributes:

- `config` –

  Default configuration options.

### ‹› `` `markdown.extensions.toc.TocExtension.config` `instance-attribute`

Default configuration options.

Defined Value:

    self.config = {
        'marker': [
            '[TOC]',
            'Text to find and replace with Table of Contents. Set to an empty string to disable. '
            'Default: `[TOC]`.'
        ],
        'title': [
            '', 'Title to insert into TOC `<div>`. Default: an empty string.'
        ],
        'title_class': [
            'toctitle', 'CSS class used for the title. Default: `toctitle`.'
        ],
        'toc_class': [
            'toc', 'CSS class(es) used for the link. Default: `toclink`.'
        ],
        'anchorlink': [
            False, 'True if header should be a self link. Default: `False`.'
        ],
        'anchorlink_class': [
            'toclink', 'CSS class(es) used for the link. Defaults: `toclink`.'
        ],
        'permalink': [
            0, 'True or link text if a Sphinx-style permalink should be added. Default: `False`.'
        ],
        'permalink_class': [
            'headerlink', 'CSS class(es) used for the link. Default: `headerlink`.'
        ],
        'permalink_title': [
            'Permanent link', 'Title attribute of the permalink. Default: `Permanent link`.'
        ],
        'permalink_leading': [
            False,
            'True if permalinks should be placed at start of the header, rather than end. Default: False.'
        ],
        'baselevel': ['1', 'Base level for headers. Default: `1`.'],
        'slugify': [
            slugify, 'Function to generate anchors based on header text. Default: `slugify`.'
        ],
        'separator': ['-', 'Word separator. Default: `-`.'],
        'toc_depth': [
            6,
            'Define the range of section levels to include in the Table of Contents. A single integer '
            '(b) defines the bottom section level (<h1>..<hb>) only. A string consisting of two digits '
            'separated by a hyphen in between (`2-5`) defines the top (t) and the bottom (b) (<ht>..<hb>). '
            'Default: `6` (bottom).'
        ],
    }

### ‹› `` `markdown.extensions.toc.TocExtension.extendMarkdown(md)`

Add TOC tree processor to Markdown.