escape flag in create_markdown is ignored when using a custom renderer – must be set manually

[NaumanHSA]

Problem

When using a custom renderer with mistune.create_markdown, the escape flag is ignored, even if explicitly passed:

markdown = mistune.create_markdown(
    renderer=renderer,
    escape=False,  # This is ignored
    hard_wrap=False
)

This results in HTML still being escaped, which can be confusing if you're expecting raw HTML rendering.

Root Cause

The create_markdown function does not propagate the escape flag to the renderer instance if you provide your own renderer. It only sets the flag if it's creating the default renderer internally.

Solution / Workaround

To make it work, you need to pass the escape flag when instantiating your custom renderer, like this:

class SectionRenderer(mistune.HTMLRenderer):
    def __init__(self, escape: bool = True):
        super().__init__(escape=escape)
        self._in_section = False
        # other logic...

renderer = SectionRenderer(escape=False)

markdown = mistune.create_markdown(
    renderer=renderer,
    hard_wrap=False
)

Now the escape=False will take effect as expected.

Recommendation

Consider one of the following improvements:

• Document this behavior in the create_markdown docstring, clarifying that escape and similar flags only apply if no custom renderer is provided.
• Propagate the flag into the renderer if the renderer accepts it (perhaps conditionally via hasattr or renderer inspection).

[lepture]

It is a design issue. When you use a custom renderer, you don't need to pass the escape parameter.

The escape parameter is used only when renderer is "html", which is the default renderer.

    elif renderer == "html":
        renderer = HTMLRenderer(escape=escape)

[stuartmaxwell]

Hello - I came here to log the same issue as the above.

"When you use a custom renderer, you don't need to pass the escape parameter" - perhaps this could be clarified in the docs? In the API reference for create_markdown it's not clear that the "escape" parameter has no effect unless using "html" as the renderer.

I ran in to this issue, by following your code example here: https://mistune.lepture.com/en/latest/guide.html#customize-renderer

In that example, if you want to use the custom HTML renderer and you don't want HTML to be escaped, then you need to pass escape=False to the custom renderer and not to the create_markdown method.

For example, this code works as expected:

class HighlightRenderer(mistune.HTMLRenderer):
    def block_code(self, code, info=None):
        if info:
            lexer = get_lexer_by_name(info, stripall=True)
            formatter = html.HtmlFormatter()
            return highlight(code, lexer, formatter)
        return '<pre><code>' + mistune.escape(code) + '</code></pre>'

markdown = mistune.create_markdown(renderer=HighlightRenderer(escape=False))

But this code does not work as expected:

class HighlightRenderer(mistune.HTMLRenderer):
    def block_code(self, code, info=None):
        if info:
            lexer = get_lexer_by_name(info, stripall=True)
            formatter = html.HtmlFormatter()
            return highlight(code, lexer, formatter)
        return '<pre><code>' + mistune.escape(code) + '</code></pre>'

markdown = mistune.create_markdown(escape=False, renderer=HighlightRenderer())

Thank you so much for working on this library - hope the above helps. :-)