html-to-markdown

What it is and what it does

html-to-markdown is a Python binding to a Rust-based HTML-to-Markdown converter designed to handle messy, real-world HTML without requiring manual parsing strategy selection or tuning. It accepts unclosed tags, malformed entities, CDATA, custom elements, nested tables, and mixed encodings, then returns clean Markdown output in a single `convert()` call. The package exposes a structured result containing the converted content, warnings, and optionally extracted metadata (Open Graph, Twitter, JSON-LD, microdata).

The converter uses a tiered dispatch strategy (byte scanner → DOM walker → html5ever repair) to achieve byte-equal output across different parsing paths, ensuring consistent results regardless of input complexity. It supports both CommonMark and Djot output formats, handles GitHub-flavored Markdown tables with alignment and cell padding, and can optionally mirror inline images. The implementation is fast enough for whole-corpus jobs and requires Python 3.10 or later; it ships as a compiled extension with pre-built wheels for major platforms.

Use it for:

• Extract clean Markdown from web scraped HTML without manual cleanup or tag-balancing logic.
• Convert email HTML bodies or rich-text editor output to Markdown for storage or downstream processing.
• Parse and extract structured metadata (Open Graph, JSON-LD) from web pages in the same pass as content conversion.
• Build content pipelines that accept arbitrary HTML and produce consistent, lossless Markdown without tuning per-source.
• Generate Markdown documentation from HTML-based CMS exports or legacy web content archives.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Converts real-world HTML—including malformed tags, broken entities, and nested tables—into clean CommonMark or Djot Markdown in a single call, with optional metadata extraction.

Yes. The package is actively maintained, has no known vulnerabilities, supports current Python versions (3.10–3.14), and solves a real problem—converting messy HTML to clean Markdown without manual intervention. Medium install friction is acceptable for a compiled extension with pre-built wheels. Use it if you need robust HTML-to-Markdown conversion in production; skip it only if you need Python <3.10 or have a simpler, pure-Python alternative already in place.

Install

html-to-markdown on PyPI

pip install html-to-markdown

uv add html-to-markdown

poetry add html-to-markdown

Installing html-to-markdown

Before you install

Medium install friction due to compiled wheels (cp310-abi3 binaries for multiple platforms), but pre-built for common architectures (x86_64, aarch64, macOS, Windows). Active maintenance with a release 9 days old and 845 repository stars.

License in practice

MIT license permits unrestricted use, modification, and distribution in commercial and private projects with minimal attribution requirements.

Quickstart

pip install html-to-markdown

from html_to_markdown import convert

result = convert('<p>Hello <b>world</b></p>')
print(result['content'])  # Hello **world**

Requires Python 3.10 or later; compiled extension wheels are platform-specific but pre-built for x86_64, aarch64, macOS, and Windows.

Verify before relying

• Whether the visitor API and metadata extraction features are exposed in the Python binding or require direct Rust access.
• Performance characteristics (19–116 MB/s cited for corpus) on typical document sizes in production Python workflows.
• Whether Djot output format is fully supported in the Python package or limited to CommonMark.

Package facts

Evidence: html_to_markdown-3.10.6-cp310-abi3-macosx_10_12_x86_64.whl; html_to_markdown-3.10.6-cp310-abi3-macosx_11_0_arm64.whl; html_to_markdown-3.10.6-cp310-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl; html_to_markdown-3.10.6-cp310-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl; html_to_markdown-3.10.6-cp310-abi3-win_amd64.whl

Keywords: converter, html, markdown

Tags

More HTML packages