markdown-it-py

markdown-it-py is a faithful Python port of the popular JavaScript markdown-it parser, giving Python projects a fast, spec-compliant CommonMark parser with a pluggable rule-based architecture. Rather than a monolithic regex-based converter, it tokenizes Markdown through a chain of block, inline, and core rules, then renders those tokens to HTML (or any other target) through a separate, overridable renderer.

This separation of parsing from rendering, plus a first-class plugin system, is what makes it the parser of choice underneath tools like MyST, Sphinx extensions, and Rich’s Markdown support: consumers can add syntax extensions (footnotes, tables, front matter) or walk the token/syntax tree directly instead of only getting a final HTML string.

What You Get

• 100% CommonMark specification compliance out of the box
• A pluggable rule chain (block, inline, core rules) instead of a monolithic parser
• A separate, overridable renderer, so you can target HTML, a tree structure, or a custom output
• A SyntaxTreeNode API for walking the parsed document as a tree rather than a flat token list
• An official plugin ecosystem (mdit-py-plugins) for footnotes, front matter, tables, and more
• A small bundled CLI for quick file-to-HTML conversion

Common Use Cases

• Powering documentation generators (Sphinx/MyST-Parser) that need CommonMark plus custom directives
• Rendering Markdown to HTML inside web apps and static site generators
• Building custom Markdown dialects by adding or removing rules and plugins
• Terminal/CLI tools (like rich) that render Markdown to formatted console output

Under The Hood

Architecture - Parsing runs through three sequential phases: parser_block.py and parser_inline.py each apply an ordered chain of rules (in rules_block/ and rules_inline/) to produce a flat token stream, parser_core.py runs post-processing core rules over that stream, and renderer.py walks the tokens to emit HTML by default; tree.py layers an optional SyntaxTreeNode view on top of the same tokens for structured traversal. Tech Stack - Modern typed Python (3.10+) with a single runtime dependency (mdurl for URL parsing), built with flit_core, and validated through tox across Python versions; ships a py.typed marker for type-checker consumers. Code Quality - The project mirrors the upstream JS markdown-it test fixtures for CommonMark conformance plus its own tests/ suite, and tracks a port.yaml file recording exact parity with the JS implementation, giving strong confidence in spec correctness. API Design - The top-level MarkdownIt().render(text) call covers the common case in one line, while the rule/plugin system (.use(plugin), .disable(rule)) exposes real extensibility for advanced consumers — a small learning curve for basic use, more depth required to customize rules.