Skip to content

rendering ¤

This module holds helpers responsible for augmentations to the Markdown sub-documents produced by handlers.

Classes:

HeadingShiftingTreeprocessor ¤

HeadingShiftingTreeprocessor(md: Markdown, shift_by: int)

Bases: Treeprocessor

Shift levels of all Markdown headings according to the configured base level.

Parameters:

  • md ¤

    (Markdown) –

    A markdown.Markdown instance.

  • shift_by ¤

    (int) –

    The number of heading "levels" to add to every heading.

Attributes:

  • shift_by (int) –

    The number of heading "levels" to add to every heading. <h2> with shift_by = 3 becomes <h5>.

shift_by instance-attribute ¤

shift_by: int = shift_by

The number of heading "levels" to add to every heading. <h2> with shift_by = 3 becomes <h5>.

Highlighter ¤

Highlighter(md: Markdown)

Bases: Highlight

Code highlighter that tries to match the Markdown configuration.

Picking up the global config and defaults works only if you use the codehilite or pymdownx.highlight (recommended) Markdown extension.

  • If you use pymdownx.highlight, highlighting settings are picked up from it, and the default CSS class is .highlight. This also means the default of guess_lang: false.

  • Otherwise, if you use the codehilite extension, settings are picked up from it, and the default CSS class is .codehilite. Also consider setting guess_lang: false.

  • If neither are added to markdown_extensions, highlighting is enabled anyway. This is for backwards compatibility. If you really want to disable highlighting even in mkdocstrings, add one of these extensions anyway and set use_pygments: false.

The underlying implementation is pymdownx.highlight regardless.

Parameters:

  • md ¤

    (Markdown) –

    The Markdown instance to read configs from.

Methods:

highlight ¤

highlight(
    src: str,
    language: str | None = None,
    *,
    inline: bool = False,
    dedent: bool = True,
    linenums: bool | None = None,
    **kwargs: Any
) -> str

Highlight a code-snippet.

Parameters:

  • src ¤

    (str) –

    The code to highlight.

  • language ¤

    (str | None, default: None ) –

    Explicitly tell what language to use for highlighting.

  • inline ¤

    (bool, default: False ) –

    Whether to highlight as inline.

  • dedent ¤

    (bool, default: True ) –

    Whether to dedent the code before highlighting it or not.

  • linenums ¤

    (bool | None, default: None ) –

    Whether to add line numbers in the result.

  • **kwargs ¤

    (Any, default: {} ) –

    Pass on to pymdownx.highlight.Highlight.highlight.

Returns:

  • str –

    The highlighted code as HTML text, marked safe (not escaped for HTML).

IdPrependingTreeprocessor ¤

IdPrependingTreeprocessor(md: Markdown, id_prefix: str)

Bases: Treeprocessor

Prepend the configured prefix to IDs of all HTML elements.

Parameters:

  • md ¤

    (Markdown) –

    A markdown.Markdown instance.

  • id_prefix ¤

    (str) –

    The prefix to add to every ID. It is prepended without any separator.

Attributes:

  • id_prefix (str) –

    The prefix to add to every ID. It is prepended without any separator; specify your own separator if needed.

id_prefix instance-attribute ¤

id_prefix: str = id_prefix

The prefix to add to every ID. It is prepended without any separator; specify your own separator if needed.

MkdocstringsInnerExtension ¤

MkdocstringsInnerExtension(headings: list[Element])

Bases: Extension

Extension that should always be added to Markdown sub-documents that handlers request (and only them).

Parameters:

  • headings ¤

    (list[Element]) –

    A list that will be populated with all HTML heading elements encountered in the document.

Methods:

extendMarkdown ¤

extendMarkdown(md: Markdown) -> None

Register the extension.

Parameters:

  • md ¤

    (Markdown) –

    A markdown.Markdown instance.

ParagraphStrippingTreeprocessor ¤

Bases: Treeprocessor

Unwraps the

element around the whole output.