CommonMark.py

CommonMark.py is a pure Python port of jgm’s commonmark.js, a Markdown parser and renderer that implements the CommonMark specification using only native Python modules. It parses Markdown text into an abstract syntax tree and can render that tree back out to HTML or other formats.

The library tracks the CommonMark spec and ships the spec’s conformance tests, giving predictable, standards-compliant Markdown handling. Note that the project is now deprecated by its maintainers, who recommend markdown-it-py for new work, but it remains widely installed as a transitive dependency across the Python ecosystem.

What You Get

• A CommonMark-compliant Markdown parser producing a traversable AST of Node objects
• An HTML renderer plus the building blocks for custom renderers
• The official CommonMark spec conformance test suite bundled in the package
• A pure-Python implementation with zero compiled dependencies

Common Use Cases

• Converting user-supplied Markdown to HTML in Python web applications
• Building custom output renderers by walking the parsed CommonMark AST
• Standards-compliant Markdown processing where CommonMark conformance matters

Under The Hood

Architecture - Parsing is split across blocks.py (block-level structure such as paragraphs, lists, and code blocks) and inlines.py (inline parsing of emphasis, links, and code spans), producing a tree of node.py Node objects. main.py wires the parser together, render/ holds the HTML renderer and rendering base classes, and helpers like entitytrans.py, normalize_reference.py, and common.py handle HTML entities and reference normalization. The design mirrors commonmark.js’s two-phase block-then-inline parse.

Tech Stack - The codebase is 100% Python with no third-party runtime dependencies, packaged via setup.py/setup.cfg. It uses tox for multi-version test orchestration and ships the CommonMark spec.txt alongside the code for conformance testing.

Code Quality - The package includes a dedicated commonmark/tests directory with spec-driven tests (run_spec_tests.py), unit tests (unit_tests.py), and reStructuredText tests, driven against the bundled spec file. The code is mature and stable, though the project is now formally deprecated and in maintenance-only mode.

API Design - The public API is deliberately minimal: commonmark.commonmark(text) returns rendered HTML in one call, while Parser and HtmlRenderer are exposed for finer control over the parse/render pipeline. This makes the common case a one-liner while still allowing AST traversal and custom renderers for advanced needs.