markdown-it-py

I've been using markdown-it-py for parsing and rendering Markdown in several Python projects, and it's been reliable overall. The API is straightforward - just instantiate MarkdownIt() and call .render() on your text. What really shines is the plugin ecosystem; extending functionality with things like tables, footnotes, or custom syntax is well-designed through the .use() method. The parser is strict by default but configurable, which helps catch malformed input early.

The main friction point is the documentation. While the README covers basics, understanding how to write custom plugins or work with the token stream requires digging through source code or referencing the original JavaScript markdown-it docs. Error messages are generally helpful for syntax issues but can be cryptic when plugin interactions cause problems. Debugging token transformation requires understanding the internal state machine, which isn't well documented.

Community support is decent - GitHub issues get responses, though not always quickly. Stack Overflow has limited coverage, so you'll often need to read the codebase. For standard use cases (basic Markdown rendering with common extensions), it's painless. Complex customization has a steeper learning curve.

In production use, markdown-it-py handles the core parsing job reliably. The library defaults to escaping HTML by default, which is critical for user-generated content scenarios. You can enable raw HTML with `html=True`, but the secure-by-default stance is appreciated. The plugin architecture is well-designed, though you need to audit third-party plugins yourself as they can bypass sanitization.

Error handling is generally predictable—malformed input produces empty strings or falls back gracefully rather than throwing exceptions that leak implementation details. The parser is reasonably resilient to malicious input patterns like deeply nested structures, though I recommend setting reasonable content length limits at the application layer. Token-level access gives you fine control for custom sanitization rules.

The dependency footprint is minimal (mainly mdurl and linkify-it-py), reducing supply chain exposure. However, there's no built-in rate limiting or resource consumption controls, so wrap it appropriately if processing untrusted input at scale. Documentation could be clearer about security implications of various options.

markdown-it-py is a faithful Python port of the JavaScript markdown-it library that handles untrusted input reasonably well. The parser is designed with security in mind—HTML is escaped by default unless you explicitly enable it, which follows secure-by-default principles. The token-based parsing approach gives you fine-grained control over rendering and makes it easier to audit what's being output.

In practice, the API is straightforward: instantiate MarkdownIt with your desired preset ('commonmark', 'default', etc.), optionally enable plugins, and call render(). The plugin system is well-architected, letting you extend functionality without monkey-patching core code. Error handling is generally good—malformed input doesn't crash the parser, though error messages could be more actionable when custom plugins misbehave.

From a security standpoint, the main footgun is the html=True flag, which allows raw HTML passthrough. You need to explicitly combine this with a sanitizer like bleach if handling untrusted content. The library doesn't warn you about this, so it's easy to create XSS vulnerabilities if you're not careful. Dependencies are minimal (mainly mdurl and linkify-it-py for optional features), which reduces supply chain risk.