markdown.extensions.toc §

Add table of contents support to Python-Markdown.

See the documentation for details.

Classes:

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], counters: dict[str, int] | None = None) -> str §

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

counters is an optional cache which maps a base id to the highest n for which base_1 through base_n are all known to be in ids. When the same cache is passed along with the same ids on every call, a repeated id skips past the suffixes which earlier calls already found to be taken rather than checking each of them again.

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

Table of Contents Extension to Python-Markdown.

Methods:

Attributes:

  • config –

    Default configuration options.

markdown.extensions.toc.TocExtension.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).']} instance-attribute §

Default configuration options.

markdown.extensions.toc.TocExtension.extendMarkdown(md) §

Register the processor.

Class Instance Registry Name Priority
TocTreeprocessor treeprocessors toc 5