html-to-markdown

Overview of html-to-markdown

What it is

A high-performance, CommonMark-compliant HTML to Markdown converter. It takes real-world HTML — including unclosed tags, CDATA, custom elements, broken entities, nested tables, and mixed encodings — and returns clean CommonMark or Djot output. The library is built on a Rust core and is available as native bindings in 16 languages: Rust, Python, Node.js, WASM, Java, Go, C#, PHP, Ruby, Elixir, R, Dart, Kotlin (Android), Swift, Zig, and a C ABI. It can also extract page metadata (Open Graph, Twitter, JSON-LD) and structured tables during the same conversion pass.

Key features

• 16 languages, one Rust core: Same result from any supported language.
• Tiered dispatch: Byte scanner → DOM walker → html5ever repair, with byte-equal output across tiers.
• Real-HTML robust: Handles unclosed tags, CDATA, custom elements, malformed entities, nested tables, mixed encodings without losing content.
• GFM tables: Padded cells, alignment, pipe escaping.
• Djot output: Set output_format = “djot” to emit Djot.
• Metadata extraction: Parses into structured metadata (Open Graph, Twitter, JSON-LD, microdata, RDFa, header hierarchy).
• Visitor API: Feature-gated traversal to transform the converted Markdown AST.
• Configurable preprocessing: Standard, strict, and lenient presets.

Use cases

• Converting messy, production HTML to clean Markdown for documentation, content migration, or analysis.
• Extracting both content and structured metadata in a single pass, e.g., for web scraping or document intelligence pipelines.
• Running batch conversions of large corpora where performance (19–116 MB/s on the Wikipedia/mdream corpus) is important.
• Integrating HTML-to-Markdown conversion into applications written in any of the 16 supported languages.

Getting started

Rustshcargo add html-to-markdown-rsSee Rust README for full documentation.Pythonshpip install html-to-markdownSee Python README for full documentation.Node.jsshpnpm add @xberg-io/html-to-markdownSee Node.js README for full documentation.Goshgo get github.com/xberg-io/html-to-markdown/packages/go/v3See Go README for full documentation.JavaAvailable on Maven Central as io.xberg:html-to-markdown. See Java README for the dependency snippet and current version.C#shdotnet add package XbergIo.HtmlToMarkdownSee C# README for full documentation.Rubyshgem install html-to-markdownSee Ruby README for full documentation.PHPThis is a native PHP extension (Rust ext-php-rs), so install it with PIE — not composer require:shpie install xberg-io/html-to-markdownSee PHP README for full documentation.ElixirAdd {:html_to_markdown, “~> 3.6”} to your mix.exs dependencies. See Elixir README for full documentation.Rrinstall.packages(“htmltomarkdown”, repos = “https://xberg-io.r-universe.dev”)See R README for full documentation.Dart / Fluttershdart pub add h2mSee Dart README for full documentation.Kotlin (Android)Available on Maven Central as io.xberg:html-to-markdown-android. See Kotlin README for the dependency snippet and current version.SwiftAdd via Swift Package Manager. See Swift README for full documentation.ZigSee Zig README for installation and usage.WebAssemblyshpnpm add @xberg-io/html-to-markdown-wasmSee WebAssembly README for full documentation.C/C++ (FFI)Pre-built .so / .dll / .dylib from GitHub Releases. See FFI crate for full documentation.CLIshcargo install html-to-markdown-cliOr install the prebuilt binary via cargo-binstall:shcargo binstall html-to-markdown-cliOr via Homebrew:shbrew install xberg-io/tap/html-to-markdownWindows users can install via Scoop:powershellscoop bucket add xberg https://github.com/xberg-io/scoop-bucketscoop install html-to-markdownSee CLI usage for full documentation.

License and pricing

Licensed under the MIT license. Pricing type is open source.

Based on the project's public README and repository metadata.