You can extend mistune.HTMLRenderer to handle custom syntax by overriding specific rendering methods. For example, to wrap text enclosed in $ in a specific HTML span, override the codespan method.

To use your custom renderer, pass an instance of it to mistune.create_markdown(renderer=...).

from mistune import HTMLRenderer, create_markdown
from markupsafe import escape

class MyRenderer(HTMLRenderer):
    def codespan(self, text):
        if text.startswith('$') and text.endswith('$'):
            return '<span class="math">' + escape(text) + '</span>'
        return '<code>' + escape(text) + '</code>'

# use customized renderer
markdown = create_markdown(renderer=MyRenderer())
print(markdown('hi `$a^2=4$`'))

Mistune provides several built-in plugins for extended Markdown syntax. You can enable them using two primary methods:

1. Using mistune.create_markdown(): Pass a list of plugin names to the plugins argument.
2. Using mistune.Markdown(): Manually instantiate the class with a renderer and a list of plugin objects imported from mistune.plugins.

Note: The speedup plugin is deprecated and ignored as its functionality is now part of the core parser.

When upgrading custom renderers from Mistune v2 to v3, several method signatures in HTMLRenderer have changed. Ensure your custom implementations match the new parameter orders and names:

• link: Now uses (self, text, url, title=None) instead of (self, link, text=None, title=None).
• image: Now uses (self, text, url, title=None) instead of (self, src, alt="", title=None).
• heading: Now accepts **attrs as (self, text, level, **attrs).
• list: Now accepts **attrs instead of (self, text, ordered, level, start=None).
• list_item: Now uses (self, text) instead of (self, text, level).
• table_cell: The is_head parameter is renamed to head in (self, text, align=None, head=False).

Beyond the core library, the community provides specialized plugins for specific output formats:

• mistune-telegram: Converts Markdown into Telegram-compatible format.
• mistune-json: Converts Markdown into HTML-based JSON objects.

You can find these extensions on GitHub to extend Mistune's capabilities.

You can customize the generated output by subclassing mistune.HTMLRenderer and passing the instance to create_markdown(renderer=...). This allows you to override specific methods, such as block_code, to implement features like syntax highlighting.

import mistune
from pygments import highlight
from pygments.lexers import get_lexer_by_name
from pygments.formatters import html


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())
print(markdown('```python\nassert 1 == 1\n```'))

For a quick and easy conversion of Markdown text to HTML with all common features enabled by default (including strikethrough, tables, and footnotes, and without HTML escaping), use the mistune.html() function.

import mistune

mistune.html(YOUR_MARKDOWN_TEXT)