{"id":3551,"library":"mistletoe","title":"Mistletoe Markdown Parser","description":"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.","status":"active","version":"1.5.1","language":"en","source_language":"en","source_url":"https://github.com/miyuchina/mistletoe","tags":["markdown","parser","renderer","html","latex","commonmark"],"install":[{"cmd":"pip install mistletoe","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Requires Python 3.5 or newer.","package":"Python","optional":false}],"imports":[{"symbol":"markdown","correct":"from mistletoe import markdown"},{"symbol":"HTMLRenderer","correct":"from mistletoe import Document, HTMLRenderer"},{"symbol":"LaTeXRenderer","correct":"from mistletoe import Document, LaTeXRenderer"},{"note":"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`.","wrong":"from mistletoe.pygments_renderer import PygmentsRenderer","symbol":"PygmentsRenderer","correct":"from mistletoe.contrib.pygments_renderer import PygmentsRenderer"}],"quickstart":{"code":"from mistletoe import markdown\n\n# Basic Markdown to HTML conversion\nmarkdown_text = \"# Hello, Mistletoe!\\n\\nThis is **bold** text and `code`.\"\nhtml_output = markdown(markdown_text)\nprint(f\"Basic HTML output:\\n{html_output}\\n\")\n\n# Using a custom renderer to modify output\nfrom mistletoe import Document, HTMLRenderer\n\nclass CustomHTMLRenderer(HTMLRenderer):\n    def render_heading(self, token):\n        # Add a custom class to all headings\n        return f'<h{token.level} class=\"custom-heading\">{self.render_inner(token)}</h{token.level}>'\n\nwith CustomHTMLRenderer() as renderer:\n    document = Document(markdown_text)\n    custom_html = renderer.render(document)\nprint(f\"Custom HTML output:\\n{custom_html}\")","lang":"python","description":"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."},"warnings":[{"fix":"Update import statements from `from mistletoe.<renderer> import ...` to `from mistletoe.contrib.<renderer> import ...`.","message":"The `contrib` module (containing renderers like `PygmentsRenderer`) was moved from directly under the `mistletoe` package to `mistletoe.contrib`.","severity":"breaking","affected_versions":"v1.0.0 and newer"},{"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.","message":"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.","severity":"breaking","affected_versions":"v1.4.0 and newer"},{"fix":"Ensure your project is running on Python 3.5 or a newer compatible version.","message":"Python 3.5 became the minimum required version. Older Python versions are no longer supported.","severity":"breaking","affected_versions":"v0.9.0 and newer"},{"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.","message":"By default, tables are now allowed to interrupt paragraphs, aligning with GFM behavior. This might change parsing results for certain Markdown inputs.","severity":"gotcha","affected_versions":"v1.2.0 and newer"},{"fix":"Use the more versatile `FileWrapper.get_pos()` and `FileWrapper.set_pos()` methods instead.","message":"The `FileWrapper.anchor()` and `FileWrapper.reset()` methods are deprecated.","severity":"deprecated","affected_versions":"v1.2.0 and newer"},{"fix":"Remove any custom HTML unescaping logic from your renderers, as this is now handled upstream by the parser.","message":"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.","severity":"breaking","affected_versions":"v0.9.0 and newer"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}