Mistletoe Markdown Parser

1.5.1 · active · verified Sat Apr 11

Mistletoe is a fast, extensible Markdown parser written in pure Python. It fully supports the CommonMark specification and provides various renderers for output formats like HTML, LaTeX, and even back to Markdown. The library is actively maintained, with the current stable version being 1.5.1, and releases occurring every few months for bug fixes and minor feature enhancements.

Warnings

breaking The `contrib` module (containing renderers like `PygmentsRenderer`) was moved from directly under the `mistletoe` package to `mistletoe.contrib`.
Fix: Update import statements from `from mistletoe.<renderer> import ...` to `from mistletoe.contrib.<renderer> import ...`.
breaking The `children` attribute of tokens changed to a property. Direct checks like `hasattr(token, 'children')` or `'children' in vars(token)` no longer work as expected.
Fix: Replace checks with `token.children is not None` to determine if a token has children, or use `token.children or []` to safely access children, providing an empty list if none exist.
breaking Python 3.5 became the minimum required version. Older Python versions are no longer supported.
Fix: Ensure your project is running on Python 3.5 or a newer compatible version.
gotcha By default, tables are now allowed to interrupt paragraphs, aligning with GFM behavior. This might change parsing results for certain Markdown inputs.
Fix: If you require the old behavior where tables do not interrupt paragraphs, set `mistletoe.block_token.Table.interrupt_paragraph = False` at the start of your application.
deprecated The `FileWrapper.anchor()` and `FileWrapper.reset()` methods are deprecated.
Fix: Use the more versatile `FileWrapper.get_pos()` and `FileWrapper.set_pos()` methods instead.
breaking HTML character references (entities) are now correctly unescaped during the parsing phase. Custom renderers that previously performed their own unescaping might double-unescape or behave unexpectedly.
Fix: Remove any custom HTML unescaping logic from your renderers, as this is now handled upstream by the parser.

Install

pip install mistletoe Install stable version

Imports

markdown
```
from mistletoe import markdown
```

HTMLRenderer

from mistletoe import Document, HTMLRenderer

LaTeXRenderer

from mistletoe import Document, LaTeXRenderer

PygmentsRenderer
```
from mistletoe.contrib.pygments_renderer import PygmentsRenderer
```
Prior to v1.0.0, renderers in the 'contrib' module were directly under the `mistletoe` package. Since v1.0.0, they moved to `mistletoe.contrib`.

Quickstart

This quickstart demonstrates basic Markdown to HTML conversion using the `mistletoe.markdown` function and how to extend `HTMLRenderer` to customize the output, such as adding a CSS class to headings.

from mistletoe import markdown

# Basic Markdown to HTML conversion
markdown_text = "# Hello, Mistletoe!\n\nThis is **bold** text and `code`."
html_output = markdown(markdown_text)
print(f"Basic HTML output:\n{html_output}\n")

# Using a custom renderer to modify output
from mistletoe import Document, HTMLRenderer

class CustomHTMLRenderer(HTMLRenderer):
    def render_heading(self, token):
        # Add a custom class to all headings
        return f'<h{token.level} class="custom-heading">{self.render_inner(token)}</h{token.level}>'

with CustomHTMLRenderer() as renderer:
    document = Document(markdown_text)
    custom_html = renderer.render(document)
print(f"Custom HTML output:\n{custom_html}")

view raw JSON →