‹› markdown.extensions.toc

Add table of contents support to Python-Markdown.

See the documentation for details.

‹› 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.

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

‹› 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.