htomd

Extract Markdown and metadata from HTML. Pure Python 3.12+, with no runtime dependencies or network access.

Installation

python -m pip install htomd

For the command line, install in an isolated tool environment:

uv tool install htomd

Python API

import htomd

html = "<article><h1>Hello</h1><p>Readable text.</p></article>"
markdown = htomd.convert(html)
document = htomd.extract(html, url="https://example.com/article")
print(document.markdown, document.metadata.title, document.diagnostics)

Pass decoded HTML strings. url resolves relative references. extract() returns immutable results; missing metadata is None. Empty content yields empty Markdown; invalid argument types raise TypeError.

Best suited to articles and documentation. Extraction can miss content or retain clutter. JavaScript, browser layout, math, and SVG are unsupported. Simple tables use GFM; complex tables become row/cell text.

Command line

Installing the package also installs the htomd command. To install a locally built wheel in a virtual environment:

python -m venv .venv
source .venv/bin/activate
python -m pip install dist/htomd-0.1.1-py3-none-any.whl

In Windows PowerShell, activate with .venv\Scripts\Activate.ps1 instead. See Contributing for the build commands.

curl -s https://example.com/article | htomd convert --url https://example.com/article
cat page.html | htomd convert > page.md
cat page.html | htomd extract > page.json

Both commands read stdin to EOF and accept no file arguments. Input must be UTF-8 (an optional UTF-8 BOM is accepted); output is UTF-8. --url supplies source context for relative references and metadata; it never fetches the URL.

convert writes Markdown unchanged. extract writes indented JSON containing markdown, metadata, and diagnostics, matching the Python result structure. Missing metadata is null; diagnostic notes are an array. Empty or malformed HTML receives the same best-effort handling as the library.

Run htomd, htomd help, or htomd --help for usage and pipeline examples. Use htomd help convert or htomd convert --help for command-specific help (likewise for extract). htomd version or htomd --version prints the installed package version. Help and version commands exit successfully without reading stdin.

python -m htomd supports the same commands. Successful conversion exits with code 0, I/O and decoding failures with code 1, and usage errors with code 2. Errors go to stderr.

Performance

Measured 2026-09-09 on Apple M5 Max (arm64, 36 GiB RAM), macOS-26.5.1-arm64-arm-64bit-Mach-O, Python 3.14.7. 115 offline sanitised pages, 12.82 MiB input. Single-threaded; five fresh rounds. Relative speed = competitor time / htomd time; above 1 means htomd is faster.

Dependency counts include all installed direct and transitive runtime packages, excluding the library itself, interpreter and installer tools. No optional extras were selected. Counts come from the saved isolated installations. Bundled native code and Rust/C libraries are not counted as Python packages: zero package dependencies does not mean pure Python.

Defaults perform different work: htomd.convert() selects content and extracts metadata; Trafilatura extracts main content with Markdown output selected. markdownify, html2text, and htmd-py convert markup; html-to-markdown returns content and metadata with its defaults. Output size and extraction coverage differ. These timings do not measure output quality.

RSS includes the interpreter, imports, decoded corpus and native allocations. Import time excludes interpreter startup; filesystem caches may be warm. Wheel size is the package alone; installed size includes transitive dependencies, excluding interpreter, installer tools and generated bytecode.

See methodology and reproduction, detailed results and failures, and raw measurements.

Development

mise trust
mise install
mise run setup
mise exec -- uv run --locked pytest

mise run check runs all checks. See CONTRIBUTING.md for hooks and releases.

MIT license, copyright 2026 JXD Ltd. Fixtures have separate licenses.