Upgrade Guide

Upgrade from v2 to v3


When customizing renderers, these methods’ parameters are changed:

-    link(self, link, text=None, title=None)
+    link(self, text, url, title=None)

-    image(self, src, alt="", title=None)
+    image(self, alt, url, title=None)

-    heading(self, text, level)
+    heading(self, text, level, **attrs)

-    list(self, text, ordered, level, start=None)
+    list(self, text, ordered, **attrs)

-    list_item(self, text, level)
+    list_item(self, text)

-    table_cell(self, text, align=None, is_head=False)
+    table_cell(self, text, align=None, head=False)

For plugins:

- abbr(self, key, definition)
+ abbr(self, text: str, title: str)

- task_list_item(self, text: str, level: int, checked: bool)
+ task_list_item(self, text: str, checked: bool)


There is no AstRenderer in v3, just pass None or 'ast' to create_markdown:

import mistune

md = mistune.create_markdown(renderer='ast') # or render=None
md('...markdown text...')


Please check the advanced guide and built-in plugins source code to find out how to write a mistune plugin.


Find out all the details in Directives. In v3, there is one more style of directive – fenced style directive.