Mistune Markdown Parser

Common errors

• AttributeError: module 'mistune' has no attribute 'BlockGrammar'

  cause This error frequently occurs when a project or a dependency (like `nbconvert` or `m2r`) is written for `mistune` v0.x or v1.x, but `mistune` v2.x or v3.x (like 3.2.0) is installed, as the internal API, including `BlockGrammar`, was completely redesigned in `mistune` v2 and is no longer directly exposed.
  fix If this error originates from a dependent package, try updating that package to a version compatible with `mistune` v3.2.0. If no compatible version exists, you might need to downgrade `mistune` to `mistune<2` (e.g., `pip install "mistune<2"`) to match the dependent package's requirements. If you are directly using `mistune`, refactor your code to use the modern `mistune` v3.x API for custom parsers and renderers, which involves `mistune.create_markdown` and custom renderer classes or plugins.

• ImportError: cannot import name 'AstRenderer' from 'mistune.renderers'

  cause In `mistune` v3.x (including 3.2.0), `AstRenderer` (and `HTMLRenderer`) are no longer imported from `mistune.renderers`. Instead, they are directly available under the `mistune` namespace or by using the `renderer` argument in `mistune.create_markdown`.
  fix Change the import statement from `from mistune.renderers import AstRenderer` to `from mistune import AstRenderer` (or `HTMLRenderer`). Alternatively, use `markdown = mistune.create_markdown(renderer="ast")` for AST output.

• ModuleNotFoundError: No module named 'mistune'

  cause The `mistune` library is not installed in the current Python environment or is not accessible on the `sys.path`.
  fix Install the library using pip: `pip install mistune`.

• ModuleNotFoundError: No module named 'mistune.plugins'

  cause This error can occur if you are trying to import plugins directly from `mistune.plugins` in an older `mistune` version (pre-v2) where they might not have existed, or if there's a problem with how plugins are accessed in a v3 installation. In `mistune` v3.2.0, standard plugins are typically used by passing their names as strings to `mistune.create_markdown(plugins=[...])` or by importing specific plugin functions from `mistune.plugins` for custom configurations.
  fix Ensure you are using `mistune` v3.x. For built-in plugins, pass their names as strings to `mistune.create_markdown`: `markdown = mistune.create_markdown(plugins=['strikethrough', 'table'])`. If you need to customize or create a plugin, you would import its base components, e.g., `from mistune.plugins import strikethrough`.

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
  wrong:

  from mistune import Markdown
  renderer = mistune.HTMLRenderer()
  markdown = Markdown(renderer, plugins=['strikethrough'])

  correct:

  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)