html2text

html2text is a Python library and command-line tool that turns HTML markup into clean, readable plain text formatted as valid Markdown. Originally written by Aaron Swartz and now maintained by Alireza Savand, it walks the DOM with Python’s built-in html.parser and reconstructs headings, emphasis, lists, links, images, blockquotes, and tables as their Markdown equivalents, rather than simply stripping tags.

The library exposes a configurable HTML2Text class with dozens of toggles covering link handling, image alt-text defaults, table padding, line wrapping, and Unicode vs. ASCII punctuation, so callers can tune output for feeds, changelogs, email digests, or documentation pipelines. The bundled html2text CLI wraps the same options for one-off conversions from the shell, and the project ships an extensive golden-file test suite covering dozens of real-world HTML edge cases.

What You Get

• HTML2Text class - a subclass of Python’s html.parser.HTMLParser that streams HTML and emits Markdown-formatted text incrementally.
• Command-line tool - the html2text script for converting files or piped HTML from the shell without writing any Python.
• Extensive configuration options - toggles for link style, image handling, table padding, line wrapping, and Unicode punctuation.
• Google Docs export support - a google_doc mode that cleans up the inline styling Google Docs adds when exporting to HTML.

Common Use Cases

• RSS/email digest generation - convert HTML feed entries or email bodies into readable plain-text summaries.
• Documentation pipelines - normalize scraped or CMS-exported HTML into Markdown source for static site generators.
• Content migration - bulk-convert legacy HTML content into Markdown when moving to a Markdown-based CMS or wiki.
• Web scraping post-processing - clean up scraped HTML into readable text for search indexing or LLM context windows.

Under The Hood

Architecture HTML2Text subclasses Python’s stdlib html.parser.HTMLParser and overrides its tag/data handlers to build Markdown output incrementally into an internal text buffer, tracking nested state (lists, tables, blockquotes, anchors) via instance attributes and small helper dataclasses in elements.py. config.py centralizes every default toggle as a module-level constant, utils.py holds pure formatting helpers (escaping, Google-style CSS parsing, list numbering), and cli.py is a thin argparse adapter that instantiates HTML2Text and maps CLI flags onto its instance attributes. The layering is simple (config -> core parser class -> CLI adapter) with no dependency injection; because most state lives directly as attributes on one large parser subclass rather than an isolated state object, changing the core tag-handling logic tends to ripple across many of the class’s methods.

Tech Stack The runtime has zero dependencies — it relies entirely on the Python standard library (html.parser, re, string, urllib.parse, textwrap). Packaging uses setuptools with setuptools_scm for git-tag-derived versioning, written to html2text/_version.py at build time. Dev tooling includes pytest for tests, tox for a multi-version test matrix, mypy for type checking (the package ships a py.typed marker), and Flake8, Black, and isort for linting/formatting, all pinned in pyproject.toml. CI runs on GitHub Actions with a separate workflow for PyPI publishing, and Codecov tracks coverage.

Code Quality Tests live in test/test_html2text.py and drive a golden-file harness that iterates dozens of paired .html/.md fixtures, running each through both the Python API and the CLI subprocess to check output parity — solid regression coverage, though it’s snapshot-style rather than unit tests of individual internal methods. Typing is present via a py.typed marker and mypy configuration, though the core module mixes typed and loosely-typed sections. There’s no custom exception hierarchy; parsing errors mostly surface as whatever html.parser raises. Naming is consistent snake_case throughout, and CI enforces flake8/black/mypy via a dedicated tox environment.

API Design The public surface is minimal and idiomatic: html2text.html2text(html_string) for one-shot conversion, or html2text.HTML2Text() for a configurable instance with a .handle() method. Configuration is exposed as plain instance attributes (bodywidth, ignore_links, wrap_tables, and so on) rather than a dedicated config object, which keeps the common case terse but makes the full option surface hard to discover without reading the source or docs/usage.md. Documentation covers the basics well, though the CLI’s roughly thirty flags are where most individual options are actually explained.