Mistune Integration

pymdtools.mistune_integration is the compatibility layer between pymdtools and the external mistune package. It targets Mistune 3 and provides renderers that preserve pymdtools’ historical close() hook.

Common Usage

Create a Markdown parser with close-hook support:

from pymdtools.mistune_integration import create_markdown_with_close

markdown = create_markdown_with_close(renderer="html")
html = markdown("# Title")

Use MdRenderer when Markdown should be normalized back to Markdown.

Public API

The module also re-exports selected Mistune classes and helpers for backward compatibility. The generated API below focuses on pymdtools’ own compatibility objects.

Mistune 3 integration helpers.

This module is the single integration point between pymdtools and the external mistune package. It deliberately targets the modern Mistune API and does not fall back to the old vendored implementation.

Responsibilities:

  • fail early when the installed mistune package is older than version 3;

  • re-export the Mistune objects used by the rest of the package;

  • provide renderers that preserve pymdtools’ historical close() hook;

  • expose a small helper to create Markdown parsers using those renderers.

The close() hook is intentionally opt-in: when a renderer defines a callable close method, its returned text is appended after Mistune has rendered all tokens. Renderers without close behave exactly like their Mistune base class.

Typical usage:

>>> markdown = create_markdown_with_close(renderer="html")
>>> markdown("# Title")
'<h1>Title</h1>\n'

Custom renderers can add final content by defining close:

>>> class Renderer(MdRenderer):
...     def close(self) -> str:
...         return "\n<!-- closed -->"
>>> markdown = create_markdown_with_close(renderer=Renderer())
>>> markdown("# Title").endswith("<!-- closed -->")
True
class pymdtools.mistune_integration.ClosingHTMLRenderer(escape: bool = True, allow_harmful_protocols: bool | Iterable[str] | None = None)

Bases: HTMLRenderer

HTML renderer with pymdtools’ close() hook support.

Subclass this renderer and define close(self) -> str to append final HTML after normal Markdown rendering.

This class is intended for Markdown-to-HTML conversion paths such as pymdtools.mdtopdf.converter_md_to_html_mistune().

class pymdtools.mistune_integration.ClosingMarkdownRenderer

Bases: MarkdownRenderer

Markdown renderer with pymdtools’ close() hook support.

Subclass this renderer and define close(self) -> str to append final Markdown after normal rendering.

This is the base class for Markdown-to-Markdown workflows, for example normalization and translation helpers that preserve Markdown structure.

class pymdtools.mistune_integration.MdRenderer

Bases: ClosingMarkdownRenderer

Render Mistune tokens back to Markdown for pymdtools workflows.

The base implementation comes from Mistune 3’s MarkdownRenderer. Custom pymdtools renderers can subclass this class and optionally define close(self) -> str to append final closing content after rendering.

MdRenderer exists as the stable pymdtools-facing name for Markdown output renderers. It keeps callers independent from Mistune’s internal renderer module layout.

pymdtools.mistune_integration.create_markdown_with_close(renderer: Any = 'html', **kwargs: Any) → Any

Create a Mistune Markdown parser with close() support for renderers.

Parameters:

  • renderer – Mistune renderer name or renderer instance. "html" and "markdown" are replaced by the pymdtools closing-aware renderers.

  • **kwargs – Forwarded to mistune.create_markdown().

Returns:

A configured Mistune Markdown parser.

pymdtools.mistune_integration.get_backend_name() → str

Return the active Markdown backend name.

Returns:

Always "mistune".

pymdtools.mistune_integration.get_backend_version() → str

Return the installed Mistune version string.

Returns:

Mistune __version__ when available, otherwise "unknown".