https://github.com/xberg-io/html-to-markdown
High performance and CommonMark compliant HTML to Markdown converter. Maintained by the Kreuzberg team. Kreuzberg is a fast, polyglot document intelligence engine with a Rust core. It extracts structured data from 56+ document formats using streaming parsers and built-in OCR.
https://github.com/xberg-io/html-to-markdown
hocr html html-converter markdown markdown-converter rag text-extraction text-processing
Last synced: 1 day ago
JSON representation
High performance and CommonMark compliant HTML to Markdown converter. Maintained by the Kreuzberg team. Kreuzberg is a fast, polyglot document intelligence engine with a Rust core. It extracts structured data from 56+ document formats using streaming parsers and built-in OCR.
- Host: GitHub
- URL: https://github.com/xberg-io/html-to-markdown
- Owner: xberg-io
- License: mit
- Created: 2025-02-03T16:18:12.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2026-07-07T16:54:46.000Z (4 days ago)
- Last Synced: 2026-07-09T08:06:15.103Z (2 days ago)
- Topics: hocr, html, html-converter, markdown, markdown-converter, rag, text-extraction, text-processing
- Language: HTML
- Homepage: https://docs.html-to-markdown.xberg.io
- Size: 150 MB
- Stars: 802
- Watchers: 6
- Forks: 61
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Citation: CITATION.cff
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
Awesome Lists containing this project
- fucking-awesome-rust - xberg-io/html-to-markdown - to-markdown-rs](crates.io/crates/html-to-markdown-rs)] - Fast, CommonMark-compliant HTML to Markdown converter with a Rust core and bindings for 12 languages. (Libraries / Text processing)
- fucking-awesome-python - html-to-markdown - A fast, CommonMark-compliant HTML to Markdown converter with a Rust core, tolerant of malformed HTML. (Projects / HTML Manipulation)
- fucking-awesome-java - html-to-markdown - Converts HTML to CommonMark-compatible Markdown through a Java binding. (Projects / Document Processing)
README
# html-to-markdown
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/packages/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
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 the [`xberg-io/plugins`](https://github.com/xberg-io/plugins) marketplace. 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/plugins
/plugin install html-to-markdown@xberg-io
```
Codex CLI
```text
/plugins add https://github.com/xberg-io/plugins
```
Then search for `html-to-markdown` and select **Install Plugin**.
Cursor
Settings → Plugins → Add from URL → `https://github.com/xberg-io/plugins`, then select **html-to-markdown**.
Gemini CLI
```text
gemini extensions install https://github.com/xberg-io/plugins
```
Factory Droid
```text
droid plugin marketplace add https://github.com/xberg-io/plugins
droid plugin install html-to-markdown@xberg-io
```
GitHub Copilot CLI
```text
copilot plugin marketplace add https://github.com/xberg-io/plugins
copilot plugin install html-to-markdown@xberg-io
```
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
- [Xberg](https://github.com/xberg-io/xberg) — document intelligence: text, tables, metadata from 91+ formats with optional OCR.
- [Xberg Enterprise](https://github.com/xberg-io/xberg-enterprise) — managed extraction API with SDKs, dashboards, and observability.
- [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 143 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.