Mistune Markdown Parser

Warnings

• breaking Mistune v3 introduced significant breaking changes compared to v2, particularly in custom renderer methods' parameters and the redesign of directives. Migrating existing code, especially custom plugins or renderers, will require updates.
  Fix: Refer to the official 'Upgrade Guide' for detailed changes. Parameter signatures for custom renderer methods and directive handling have been altered. For instance, `RstDirective` was renamed to `RSTDirective`.
• gotcha The default behavior for HTML escaping differs between `mistune.html()` and `mistune.create_markdown()`. `mistune.html()` does not escape raw HTML tags by default, while `mistune.create_markdown()` (without `escape=False`) *does* escape HTML.
  Fix: If using `create_markdown()`, explicitly set `escape=False` in its parameters if you want raw HTML to be rendered directly: `mistune.create_markdown(escape=False)`. Always be mindful of potential XSS vulnerabilities when disabling HTML escaping for untrusted input.
• gotcha While a global `mistune.markdown()` function exists, for performance-critical applications or when using custom configurations and plugins, it is recommended to create and reuse a `Markdown` instance (e.g., via `mistune.create_markdown()`) rather than calling the global function repeatedly.
  Fix: Initialize a Markdown instance once using `markdown = mistune.create_markdown(...)` and then call `markdown(text)` for subsequent conversions.
• gotcha Versions of Mistune v3 prior to 3.0.2 experienced a `RecursionError` when parsing complex lists.
  Fix: Upgrade to `mistune>=3.0.2` to resolve potential `RecursionError` issues with list parsing.

Install

• pip install mistune Install latest stable version

Imports

• html

  import mistune
  html_output = mistune.html(markdown_text)

  The `mistune.html()` function is the recommended high-level entry point for converting Markdown to HTML with common features enabled by default (e.g., no HTML escape, strikethrough, table, footnote plugins).
• create_markdown

  from mistune import create_markdown
  markdown = create_markdown(plugins=['strikethrough'])
  html_output = markdown(markdown_text)

  `create_markdown()` is the preferred factory function for creating customizable Markdown instances with specific renderers and plugins, simplifying setup compared to manually instantiating `Markdown` and `HTMLRenderer`.

Quickstart

This quickstart demonstrates the simplest way to convert Markdown text to HTML using the `mistune.html()` function, which provides a default setup with many common features enabled.

import mistune

markdown_text = """
# Hello, Mistune!

This is **bold** text and `code`.

- Item 1
- Item 2
"""

html_output = mistune.html(markdown_text)
print(html_output)