Turn messy, real-world HTML into clean Markdown — from the language you already work in.
## What and Why?
Feed html-to-markdown the HTML you actually have — unclosed tags, CDATA, custom elements, broken entities, nested tables, mixed encodings — and get back clean CommonMark (or Djot) without losing content. One `convert()` call does it, and it returns the same result whether you run it from Python, TypeScript, Go, Ruby, Java, or 11 more languages.
You get more than the text: pull page metadata (Open Graph, Twitter, JSON-LD) and structured tables in the same pass, or hook into the conversion to reshape the output. It is fast enough for whole-corpus jobs, and the messy-input handling is automatic — you never choose a parsing strategy or tune anything to get correct output.
### Features
| Feature | Description |
| ------- | ----------- |
| **16 languages, one Rust core** | Rust, Python, Node.js, WASM, Java, Go, C#, PHP, Ruby, Elixir, R, Dart, Kotlin (Android), Swift, Zig, and a C ABI |
| **Tiered dispatch** | Byte scanner → DOM walker → `html5ever` repair, with byte-equal output across tiers |
| **Real-HTML robust** | Unclosed tags, CDATA, custom elements, malformed entities, nested tables, mixed encodings — handled without losing content |
| **GFM tables** | Padded cells, alignment, and pipe escaping |
| **Djot output** | Set `output_format = "djot"` to emit Djot instead of Markdown |
| **Metadata extraction** | Parse `` into structured metadata (Open Graph, Twitter, JSON-LD, microdata, RDFa, header hierarchy) |
| **Inline images** | Opt-in mirroring of data URIs and remote image references |
| **Visitor API** | Feature-gated traversal to transform the converted Markdown AST |
| **Configurable preprocessing** | Standard, strict, and lenient presets — or build your own |
| **Fast** | 19–116 MB/s on the Wikipedia/mdream corpus; per-group regression thresholds enforced on every PR |
⭐ Star this repo to show your support — it helps others discover html-to-markdown.
## Quick Start
`convert()` is the single entry point — it returns a structured result with `content`, `warnings`, and optional `metadata`.
### Language Packages
Rust
```sh
cargo add html-to-markdown-rs
```
See [Rust README](https://github.com/xberg-io/html-to-markdown/tree/main/crates/html-to-markdown) for full documentation.
Python
```sh
pip install html-to-markdown
```
See [Python README](https://github.com/xberg-io/html-to-markdown/tree/main/packages/python) for full documentation.
Node.js
```sh
npm install @xberg-io/html-to-markdown
```
See [Node.js README](https://github.com/xberg-io/html-to-markdown/tree/main/crates/html-to-markdown-node) for full documentation.
Go
```sh
go get github.com/xberg-io/html-to-markdown/packages/go/v3
```
See [Go README](https://github.com/xberg-io/html-to-markdown/tree/main/packages/go) for full documentation.
Java
Available on Maven Central as `io.xberg:html-to-markdown`. See [Java README](https://github.com/xberg-io/html-to-markdown/tree/main/packages/java) for the dependency snippet and current version.
C#
```sh
dotnet add package XbergIo.HtmlToMarkdown
```
See [C# README](https://github.com/xberg-io/html-to-markdown/tree/main/packages/csharp) for full documentation.
Ruby
```sh
gem install html-to-markdown
```
See [Ruby README](https://github.com/xberg-io/html-to-markdown/tree/main/packages/ruby) for full documentation.
PHP
This is a native PHP extension (Rust `ext-php-rs`), so install it with [PIE](https://github.com/php/pie) — not `composer require`:
```sh
pie install xberg-io/html-to-markdown
```
See [PHP README](https://github.com/xberg-io/html-to-markdown/tree/main/crates/html-to-markdown-php) for full documentation.
Elixir
Add `{:html_to_markdown, "~> 3.6"}` to your `mix.exs` dependencies. See [Elixir README](https://github.com/xberg-io/html-to-markdown/tree/main/packages/elixir) for full documentation.
R
```r
install.packages("htmltomarkdown", repos = "https://xberg-io.r-universe.dev")
```
See [R README](https://github.com/xberg-io/html-to-markdown/tree/main/packages/r) for full documentation.
Dart / Flutter
```sh
dart pub add h2m
```
See [Dart README](https://github.com/xberg-io/html-to-markdown/tree/main/packages/dart) for full documentation.
Kotlin (Android)
Available on Maven Central as `io.xberg:html-to-markdown-android`. See [Kotlin README](https://github.com/xberg-io/html-to-markdown/tree/main/packages/kotlin-android) for the dependency snippet and current version.
Swift
Add via Swift Package Manager. See [Swift README](https://github.com/xberg-io/html-to-markdown/tree/main/packages/swift) for full documentation.
Zig
See [Zig README](https://github.com/xberg-io/html-to-markdown/tree/main/packages/zig) for installation and usage.
WebAssembly
```sh
npm install @xberg-io/html-to-markdown-wasm
```
See [WebAssembly README](https://github.com/xberg-io/html-to-markdown/tree/main/crates/html-to-markdown-wasm) for full documentation.
C/C++ (FFI)
Pre-built `.so` / `.dll` / `.dylib` from [GitHub Releases](https://github.com/xberg-io/html-to-markdown/releases). See [FFI crate](https://github.com/xberg-io/html-to-markdown/tree/main/crates/html-to-markdown-ffi) for full documentation.
CLI
```sh
cargo install html-to-markdown-cli
```
```sh
# Or install the prebuilt binary via cargo-binstall:
cargo binstall html-to-markdown-cli
```
```sh
brew install xberg-io/tap/html-to-markdown
```
See [CLI usage](https://docs.html-to-markdown.xberg.io) for full documentation.
### AI Coding Assistants
Install the html-to-markdown plugin from [`xberg-io/html-to-markdown`](https://github.com/xberg-io/html-to-markdown). It ships the html-to-markdown agent skills and works with every major coding agent — expand your harness below.
Claude Code
```text
/plugin marketplace add xberg-io/html-to-markdown
/plugin install html-to-markdown@html-to-markdown
```
Codex CLI
```text
/plugins add https://github.com/xberg-io/html-to-markdown
```
Then search for `html-to-markdown` and select **Install Plugin**.
Cursor
Settings → Plugins → Add from URL → `https://github.com/xberg-io/html-to-markdown`, then select **html-to-markdown**.
Gemini CLI
```text
gemini extensions install https://github.com/xberg-io/html-to-markdown
```
Factory Droid
```text
droid plugin marketplace add https://github.com/xberg-io/html-to-markdown
droid plugin install html-to-markdown@html-to-markdown
```
GitHub Copilot CLI
```text
copilot plugin marketplace add https://github.com/xberg-io/html-to-markdown
copilot plugin install html-to-markdown@html-to-markdown
```
opencode
Add the package to `opencode.json`:
```json
{
"$schema": "https://opencode.ai/config.json",
"plugin": ["@xberg-io/opencode-html-to-markdown"]
}
```
## Documentation
Full guides, the `convert()` API for every binding, tier architecture, the metadata and visitor APIs, and performance benchmarks live at **[docs.html-to-markdown.xberg.io](https://docs.html-to-markdown.xberg.io)**.
## Part of Xberg.io
- [Xberg](https://github.com/xberg-io/xberg) — the open-source content-intelligence engine: text, tables, and metadata from 101 formats (115 file extensions), with OCR, transcription, and code intelligence. MIT.
- [Xberg Pro](https://xberg.io) — a complete self-hosted content-intelligence backend in a single container. Commercial.
- [Xberg Enterprise](https://xberg.io) — the distributed, governed content-intelligence platform, scaled on Kubernetes with team governance and support. Commercial.
- [crawlberg](https://github.com/xberg-io/crawlberg) — web crawling and scraping with HTML→Markdown and headless-Chrome fallback.
- [html-to-markdown](https://github.com/xberg-io/html-to-markdown) — fast, lossless HTML→Markdown engine.
- [liter-llm](https://github.com/xberg-io/liter-llm) — universal LLM API client with native bindings for 14 languages and 165 providers.
- [tree-sitter-language-pack](https://github.com/xberg-io/tree-sitter-language-pack) — tree-sitter grammars and code-intelligence primitives.
- [alef](https://github.com/xberg-io/alef) — the polyglot binding generator that produces every per-language binding across the 5 polyglot repos.
## Contributing
Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for setup instructions and guidelines.
## License
MIT License — see [LICENSE](LICENSE) for details.
