NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI, #2752 most downloaded on PyPI
High-performance HTML to Markdown converter
Latest stable
3.22.0
Last release 11 days ago
08 Nov 2026
Ships on a steady schedule
a new release about every 9 days
Nearly every release is documented
notes for 60 of the last 60 stable releases
Nothing withdrawn
no release was ever pulled
2 years old
214 releases · first in 2024
Drag across the ruler to compare, or tap a release to open it.
See the CHANGELOG for full details.
See the CHANGELOG for full details.
npm install html-to-markdown-node
npm install html-to-markdown-wasm
pip install html-to-markdown
brew tap goldziher/tap
brew install html-to-markdown
cargo install html-to-markdown-cli
Download the appropriate binary for your platform below.
See the CHANGELOG for full details.
See the CHANGELOG for full details.
npm install html-to-markdown-node
npm install html-to-markdown-wasm
pip install html-to-markdown
brew tap goldziher/tap
brew install html-to-markdown
cargo install html-to-markdown-cli
Download the appropriate binary for your platform below.
Your coding agent can read these notes before it upgrades. Set up the MCP server →
wasm_js backend and strip wasm-pack .gitignore files so published packages ship the compiled .wasm artifacts.See the CHANGELOG for full details.
See the CHANGELOG for full details.
npm install html-to-markdown-node
npm install html-to-markdown-wasm
pip install html-to-markdown
brew tap goldziher/tap
brew install html-to-markdown
cargo install html-to-markdown-cli
Download the appropriate binary for your platform below.
pyo3) to their latest compatible releases and refreshed lockfiles.getrandom's wasm_js feature, restoring WebAssembly builds.files list so published tarballs now include compiled .node artifacts, CommonJS shims, and typings.See the CHANGELOG for full details.
See the CHANGELOG for full details.
npm install html-to-markdown-node
npm install html-to-markdown-wasm
pip install html-to-markdown
brew tap goldziher/tap
brew install html-to-markdown
cargo install html-to-markdown-cli
Download the appropriate binary for your platform below.
See the CHANGELOG for full details.
See the CHANGELOG for full details.
npm install html-to-markdown-node
npm install html-to-markdown-wasm
pip install html-to-markdown
brew tap goldziher/tap
brew install html-to-markdown
cargo install html-to-markdown-cli
Download the appropriate binary for your platform below.
InlineImage, InlineImageWarning, and InlineImageConfig) alongside convert_with_inline_images, with dedicated regression tests.--version test updated to assert the new release number.See the CHANGELOG for full details.
See the CHANGELOG for full details.
npm install @html-to-markdown/node
npm install @html-to-markdown/wasm
pip install html-to-markdown
brew tap goldziher/tap
brew install html-to-markdown
cargo install html-to-markdown-cli
Download the appropriate binary for your platform below.
hocr_spatial_tables option on ConversionOptions (Rust, Python, CLI) with --no-hocr-spatial-tables flag to disable spatial table reconstruction when de
hocr_spatial_tables option on ConversionOptions (Rust, Python, CLI) with --no-hocr-spatial-tables flag to disable spatial table reconstruction when desired.--version output and package metadata now report version 2.2.0 consistently.See the CHANGELOG for full details.
See the CHANGELOG for full details.
brew tap goldziher/tap
brew install html-to-markdown
cargo install html-to-markdown-cli
pip install html-to-markdown
Download the appropriate binary for your platform below.
See the CHANGELOG for full details.
See the CHANGELOG for full details.
brew tap goldziher/tap
brew install html-to-markdown
cargo install html-to-markdown-cli
pip install html-to-markdown
Download the appropriate binary for your platform below.
convert_with_inline_images() function to extract embedded images during conversion
data:image/*)InlineImageConfig with options for:
HtmlExtraction with markdown, extracted images, and warningsParsingOptions class in favor of direct encoding parameter on ConversionOptionshocr_extract_tables option (always enabled for hOCR content)hocr_table_column_threshold option (uses built-in heuristics)hocr_table_row_threshold_ratio option (uses built-in heuristics)hocr/spatial.rs moduleocr_table elements, preventing false positives.exe extension on Windowsscripts/ directorySee the CHANGELOG for full details.
See the CHANGELOG for full details.
brew tap goldziher/tap
brew install html-to-markdown
cargo install html-to-markdown-cli
pip install html-to-markdown
Download the appropriate binary for your platform below.
See the CHANGELOG for full details.
See the CHANGELOG for full details.
brew tap goldziher/tap
brew install html-to-markdown
cargo install html-to-markdown-cli
pip install html-to-markdown
Download the appropriate binary for your platform below.
Version 2.0.0 represents a complete rewrite of html-to-markdown with a high-performance Rust backend, delivering 10-30x performance improvements while maintaining full backward compatibility through a v1 compatibility layer.
V2 adopts CommonMark-compliant defaults for better interoperability:
| Option | V1 Default | V2 Default | Reason |
|---|---|---|---|
list_indent_width |
4 | 2 | CommonMark standard |
bullets |
"-" | "*+-" | Cycling bullets for nested lists |
escape_asterisks |
true | false | Minimal escaping |
escape_underscores |
true | false | Minimal escaping |
escape_misc |
true | false | Minimal escaping |
newline_style |
"backslash" | "spaces" | CommonMark two-space line breaks |
code_block_style |
"backticks" | "indented" | CommonMark 4-space indent |
heading_style |
"underlined" | "atx" | CommonMark # headings |
preprocessing.enabled |
false | false | No change (opt-in) |
Migration: If you relied on v1 defaults, explicitly set options to match v1 behavior.
The following v1 CLI flags are not supported in v2. The Python CLI proxy will raise helpful error messages when these flags are used:
| Removed Flag | Reason | Migration |
|---|---|---|
--strip |
Feature removed in v2 | Remove flag (feature no longer available) |
--convert |
Feature removed in v2 | Remove flag (feature no longer available) |
Note on Redundant Flags: The following v1 flags are redundant in v2 (they match the defaults) but are silently accepted for backward compatibility:
--no-escape-asterisks, --no-escape-underscores, --no-escape-misc (v2 defaults to minimal escaping)--no-wrap (v2 defaults to no wrapping)--no-autolinks (Rust CLI defaults to no autolinks)--no-extract-metadata (Rust CLI defaults to no metadata extraction)These flags can be safely removed from your commands, or you can leave them for compatibility.
Note: The Rust CLI only supports positive flags (e.g., --escape-asterisks, --autolinks, --wrap). Negative flags (--no-*) are only supported through the Python CLI proxy for v1 compatibility.
* Item 1\n\n + Nested\n* Item 1\n + Nested\nscraper and html5everconvert(html, options, preprocessing) - primary API entry pointConversionOptions - comprehensive conversion settings (now includes encoding)PreprocessingOptions - HTML cleaning configurationConversionOptions.pyi files)convert_to_markdown() function with all v1 kwargscargo-llvm-covconverters.py, processing.py, preprocessor.py)The following v1 features were removed in v2:
code_language_callback - Removed (use code_language option for default language)strip option - Removed (use preprocessing options instead)convert option - Removed (all supported tags are converted by default)convert_to_markdown_stream() - Removed (html5ever does not support streaming parsing)custom_converters - Planned for future release with Rust and Python callback supportIf you're using the v1 API, your code will continue to work:
from html_to_markdown import convert_to_markdown
# This still works in v2!
markdown = convert_to_markdown(html, heading_style="atx")
from html_to_markdown import convert, ConversionOptions
options = ConversionOptions(heading_style="atx")
markdown = convert(html, options)
V1 CLI flags are automatically translated to v2:
# V1 style (still works)
html-to-markdown --preprocess-html --escape-asterisks input.html
# V2 style (recommended)
html-to-markdown --preprocess input.html # escaping is default
Real-world performance improvements over v1 (Apple M4):
| Document Type | Size | V2 Latency | V2 Throughput | Speedup vs V1 (2.5 MB/s) |
|---|---|---|---|---|
| Lists (Timeline) | 129KB | 0.62ms | 208 MB/s | 83x |
| Tables (Countries) | 360KB | 2.02ms | 178 MB/s | 71x |
| Mixed (Python wiki) | 656KB | 4.56ms | 144 MB/s | 58x |
V2's Rust engine delivers 60-80x higher throughput than V1's Python/BeautifulSoup implementation across real-world documents.
crates/
├── html-to-markdown/ # Core conversion library
├── html-to-markdown-py/ # Python bindings (PyO3)
└── html-to-markdown-cli/ # Native CLI binary
html_to_markdown/
├── api.py # V2 API
├── options.py # V2 configuration dataclasses
├── v1_compat.py # V1 compatibility layer
├── cli_proxy.py # CLI argument translation
├── _rust.pyi # Rust binding type stubs
└── __init__.py # Public API exports
None if using v1 compatibility layer. If migrating to v2 API:
convert_to_markdown → convertConversionOptions)| Aspect | V1 | V2 |
|---|---|---|
| Primary API | convert_to_markdown(**kwargs) |
convert(html, options, preprocessing, parsing) |
| Configuration | Keyword arguments | Dataclasses (ConversionOptions, etc.) |
| Type Safety | Basic type hints | Full .pyi stubs + generics |
| Compatibility Layer | N/A | convert_to_markdown() with v1 kwargs |
| Document Type | V1 Throughput | V2 Throughput | Speedup |
|---|---|---|---|
| Lists (Timeline) | 2.5 MB/s | 208 MB/s | 83x |
| Tables (Countries) | 2.5 MB/s | 178 MB/s | 71x |
| Mixed (Python wiki) | 2.5 MB/s | 144 MB/s | 58x |
| Average | 2.5 MB/s | 177 MB/s | 71x |
| Component | V1 | V2 |
|---|---|---|
| HTML Parser | BeautifulSoup4 / lxml | html5ever (Rust) |
| Sanitizer | Custom Python | html5ever DOM filtering |
| Conversion | Pure Python (~3,850 lines) | Pure Rust (~4,800 lines) |
| Bindings | N/A | PyO3 |
| CLI | Python wrapper | Native Rust binary |
| Dependencies | bs4, lxml, soupsieve | None (statically linked) |
| HTML | V1 Output | V2 Output |
|---|---|---|
<ul><li>Item</li></ul> |
* Item (4 spaces) |
- Item (2 spaces) |
<h1>Title</h1> |
Title\n===== |
# Title |
Text*with*stars |
Text\*with\*stars |
Text*with*stars |
<br> |
Two trailing spaces | Backslash \ |
<pre>code</pre> |
```\ncode\n``` |
Indented 4 spaces |
These differences reflect v2's alignment with CommonMark specification.
html_to_markdown/converters.py (1220 lines)html_to_markdown/processing.py (1195 lines)html_to_markdown/preprocessor.py (404 lines)html_to_markdown/whitespace.py (293 lines)html_to_markdown/utils.py (37 lines).skipTotal: ~3,850 lines of Python code removed, replaced by ~4,800 lines of Rust
abi3 for Python 3.10+ wheel reusefeat: add hocr support by @Goldziher in https://github.com/Goldziher/html-to-markdown/pull/79
Full Changelog: https://github.com/Goldziher/html-to-markdown/compare/v1.15.0...v1.16.0
feat: add support for custom navigation classes in HTML preprocessing by @tommyjs007 in https://github.com/Goldziher/html-to-markdown/pull/77
Full Changelog: https://github.com/Goldziher/html-to-markdown/compare/v1.14.1...v1.15.0
fix: resolve ancestor caching issue causing escaping inside code/pre blocks by @Goldziher in https://github.com/Goldziher/html-to-markdown/pull/78
Full Changelog: https://github.com/Goldziher/html-to-markdown/compare/v1.14.0...v1.14.1
Added html5lib parser support for enhanced HTML5 compliance and standards conformance
--source-encoding CLI parameter and source_encoding API parametererrors="replace" for encoding issues--source-encoding optionconvert_to_markdown() (resolves #73)None - This release maintains full backward compatibility while adding new features.
html5lib - For enhanced HTML5 standards compliancepip install html-to-markdown[html5lib]# For best performance (recommended)
pip install html-to-markdown[lxml]
# For maximum standards compliance
pip install html-to-markdown[html5lib]
# For all parser options
pip install html-to-markdown[lxml,html5lib]
--source-encoding instead of separate encoding parametersFull Changelog: https://github.com/Goldziher/html-to-markdown/compare/v1.13.0...v1.14.0
Parser-agnostic testing system - A comprehensive fixture system that allows tests to run with both lxml and html.parser backends, ensuring compatibili
feat: benchmark suite and optimization by @Goldziher in https://github.com/Goldziher/html-to-markdown/pull/71
Full Changelog: https://github.com/Goldziher/html-to-markdown/compare/v1.12.0...v1.12.1
feat(cli): Add encoding CLI argument by @dietervansteenwegen in https://github.com/Goldziher/html-to-markdown/pull/69
Full Changelog: https://github.com/Goldziher/html-to-markdown/compare/v1.11.0...v1.12.0
This release includes significant improvements to the test suite organization and fixes 5 critical bugs discovered through systematic coverage analysi
This release includes significant improvements to the test suite organization and fixes 5 critical bugs discovered through systematic coverage analysis.
_as_optional_set)",".split(value) instead of value.split(",")<hr> elements no longer incorrectly matched as headingsFull Changelog: https://github.com/Goldziher/html-to-markdown/compare/v1.10.0...v1.11.0
fully aligned cli with python api
list_indent_depthchore(deps): bump actions/checkout from 4 to 5 by @dependabot[bot] in https://github.com/Goldziher/html-to-markdown/pull/56
Full Changelog: https://github.com/Goldziher/html-to-markdown/compare/v1.9.0...v1.9.1
This release brings significant improvements to table handling with rowspan/colspan support, modern Python features, and comprehensive bug fixes.
This release brings significant improvements to table handling with rowspan/colspan support, modern Python features, and comprehensive bug fixes.
Resolves issues #48, #50, #51, #52
Nothing published for this version
🚀 Automatic lxml parser detection - ~30% performance boost when lxml is installed
pip install html-to-markdown[lxml]lxml when available (previously defaulted to html.parser)convert_to_markdown(html, parser="html.parser")Regular installation:
pip install html-to-markdown
With performance improvements:
pip install html-to-markdown[lxml]
Special thanks to all contributors and users who provided feedback!
Full Changelog: https://github.com/Goldziher/html-to-markdown/compare/v1.5.0...v1.6.0
feat: add tag support and fix pipe chain test on Windows by @eshreyareddy in https://github.com/Goldziher/html-to-markdown/pull/30
Full Changelog: https://github.com/Goldziher/html-to-markdown/compare/v1.4.0...v1.5.0
No breaking changes to existing APIs
⏺ Release Notes - html-to-markdown v1.4.0
🎉 New Features
Strip Newlines Option
convert_to_markdown(html, strip_newlines=True)
html-to-markdown --strip-newlines input.html
🐛 Bug Fixes
Images in Tables Fixed
Before (broken): | Go one page back | Opens the last page |
After (fixed): | Go one page back | Opens the last page |
🔧 Improvements
Enhanced Project Configuration
Code Quality Enhancements
📋 Technical Details
New Parameters
CLI Options
Compatibility
Testing
🚀 Migration Guide
No migration needed! This is a fully backward-compatible release. All existing code will continue to work exactly as before.
To use the new features: from html_to_markdown import convert_to_markdown
result = convert_to_markdown(html, strip_newlines=True)
🙏 Acknowledgments
Special thanks to the community for reporting these issues:
Both issues have been resolved with comprehensive test coverage and maintain full backward compatibility.
Bump astral-sh/setup-uv from 5 to 6 by @dependabot in https://github.com/Goldziher/html-to-markdown/pull/11
Full Changelog: https://github.com/Goldziher/html-to-markdown/compare/v1.3.2...v1.3.3
fix: ensure eol before headings by @jfouret in https://github.com/Goldziher/html-to-markdown/pull/10
Full Changelog: https://github.com/Goldziher/html-to-markdown/compare/v1.3.1...v1.3.2
test: add simple test for idempotence of convert_to_markdown() by @raaaaaymond in https://github.com/Goldziher/html-to-markdown/pull/7
convert_to_markdown() by @raaaaaymond in https://github.com/Goldziher/html-to-markdown/pull/7Full Changelog: https://github.com/Goldziher/html-to-markdown/compare/v1.3.0...v1.3.1
fix: cli not defined in pyproject.toml and add support for custom converters by @Goldziher in https://github.com/Goldziher/html-to-markdown/pull/4
Full Changelog: https://github.com/Goldziher/html-to-markdown/compare/v1.2.1...v1.3.0
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
One column per month.