Renderers¶

Mistune has several built-in renderers, including:

You’re welcome to contribute more renderers.

Customize HTMLRenderer¶

You can customize HTML output with your own renderers. Take an example, we’re going to add an inline math syntax like below:

`$a^2=4$`

To render this syntax, we can create a subclass of mistune.HTMLRenderer:

from mistune import HTMLRenderer

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 = mistune.create_markdown(renderer=MyRenderer())
print(markdown('hi `$a^2=4$`'))

Available methods¶

Here is a a list of available renderer functions for HTMLRenderer, including methods on plugins:

# inline level
text(self, text)
link(self, text, url, title=None)
image(self, alt, url, title=None)
emphasis(self, text)
strong(self, text)
codespan(self, text)
linebreak(self)
softbreak(self)
inline_html(self, html)

# block level
paragraph(self, text)
heading(self, text, level, **attrs)
blank_line(self)
thematic_break(self)
block_text(self, text)
block_code(self, code, info=None)
block_quote(self, text)
block_html(self, html)
block_error(self, html)
list(self, text, ordered, **attrs)
list_item(self, text, **attrs)

# provided by strikethrough plugin
strikethrough(self, text)

# provided by mark plugin
mark(self, text)

# provided by insert plugin
insert(self, text)

# provided by subscript plugin
subscript(self, text)

# provided by abbr plugin
abbr(self, text, title)

# provided by ruby plugin
ruby(self, text, rt)

# provided by task_lists plugin
task_list_item(self, text, checked=False, **attrs)

# provide by table plugin
table(self, text)
table_head(self, text)
table_body(self, text)
table_row(self, text)
table_cell(self, text, align=None, head=False)

# provided by footnotes plugin
footnote_ref(self, key, index)
footnotes(self, text)
footnote_item(self, text, key, index)

# provide by def_list plugin
def_list(self, text)
def_list_head(self, text)
def_list_item(self, text)

# provide by math plugin
block_math(self, text)
inline_math(self, text)

RestructuredText Renderer¶

The RSTRenderer can be used to convert markdown text to RestructuredText.

from mistune.renderers.rst import RSTRenderer

convert_rst = mistune.create_markdown(renderer=RSTRenderer())
convert_rst(your_markdown_text)

Markdown Renderer¶

The MarkdownRenderer can be used to reformat your Markdown text.

from mistune.renderers.markdown import MarkdownRenderer

format_markdown = mistune.create_markdown(renderer=MarkdownRenderer())
format_markdown(your_markdown_text)

With plugins¶

The original MarkdownRenderer can ONLY render the basic Markdown syntax. If you’re using plugins, you would need to customize MarkdownRenderer with extra render methods. Take an example, you are going to add the strikethrough plugin:

from mistune.renderers.markdown import MarkdownRenderer

class MyRenderer(MarkdownRenderer):
    def strikethrough(self, token, state):
        return '~~' + self.render_children(token, state) + '~~'

format_markdown = mistune.create_markdown(renderer=MarkdownRenderer(), plugins=['strikethrough'])
format_markdown(your_markdown_text)

Default methods¶

Here is a a list of default renderer functions of MarkdownRenderer:

# inline level
text(self, token, state)
link(self, token, state)
image(self, token, state)
emphasis(self, token, state)
strong(self, token, state)
codespan(self, token, state)
linebreak(self, token, state)
softbreak(self, token, state)
inline_html(self, token, state)

# block level
paragraph(self, token, state)
heading(self, token, state)
blank_line(self, token, state)
thematic_break(self, token, state)
block_text(self, token, state)
block_code(self, token, state)
block_quote(self, token, state)
block_html(self, token, state)
block_error(self, token, state)
list(self, token, state)