html-to-markdown

High-performance HTML → Markdown conversion powered by Rust. Shipping as a Rust crate, Python package, Ruby gem, Node.js bindings, WebAssembly, and standalone CLI with identical rendering behaviour.

Experience WebAssembly-powered HTML to Markdown conversion instantly in your browser. No installation needed!

• Blazing Fast: Rust-powered core delivers 10-80× faster conversion than pure Python alternatives
• Universal: Works everywhere - Node.js, Bun, Deno, browsers, Python, Rust, and standalone CLI
• Smart Conversion: Handles complex documents including nested tables, code blocks, task lists, and hOCR OCR output
• Highly Configurable: Control heading styles, code block fences, list formatting, whitespace handling, and HTML sanitization
• Tag Preservation: Keep specific HTML tags unconverted when markdown isn't expressive enough
• Secure by Default: Built-in HTML sanitization prevents malicious content
• Consistent Output: Identical markdown rendering across all language bindings

• JavaScript/TypeScript guides:
  • Node.js/Bun (native) – Node.js README
  • WebAssembly (universal) – WASM README
• Python guide – Python README
• Ruby guide – Ruby README
• Rust guide – Rust README
• Contributing – CONTRIBUTING.md ⭐ Start here!
• Changelog – CHANGELOG.md

Node.js / Bun (Native - Fastest):

import { convert } from 'html-to-markdown-node';

const html = '<h1>Hello</h1><p>Rust ❤️ Markdown</p>';
const markdown = convert(html, {
  headingStyle: 'Atx',
  codeBlockStyle: 'Backticks',
  wrap: true,
  preserveTags: ['table'], // NEW in v2.5: Keep complex HTML as-is
});

Deno / Browsers / Edge (Universal):

import { convert } from "npm:html-to-markdown-wasm"; // Deno
// or: import { convert } from 'html-to-markdown-wasm'; // Bundlers

const markdown = convert(html, {
  headingStyle: 'atx',
  listIndentWidth: 2,
});

Performance: Native bindings average ~19k ops/sec, WASM averages ~16k ops/sec (benchmarked on complex real-world documents).

See the JavaScript guides for full API documentation:

• Node.js/Bun guide
• WebAssembly guide

# Convert a file
html-to-markdown input.html > output.md

# Stream from stdin
curl https://example.com | html-to-markdown > output.md

# Apply options
html-to-markdown --heading-style atx --list-indent-width 2 input.html

from html_to_markdown import convert, convert_with_inline_images, InlineImageConfig

html = "<h1>Hello</h1><p>Rust ❤️ Markdown</p>"
markdown = convert(html)

markdown, inline_images, warnings = convert_with_inline_images(
    '<img src="data:image/png;base64,...==" alt="Pixel">',
    image_config=InlineImageConfig(max_decoded_size_bytes=1024, infer_dimensions=True),
)

use html_to_markdown_rs::{convert, ConversionOptions, HeadingStyle};

let html = "<h1>Welcome</h1><p>Fast conversion</p>";
let markdown = convert(html, None)?;

let options = ConversionOptions {
    heading_style: HeadingStyle::Atx,
    ..Default::default()
};
let markdown = convert(html, Some(options))?;

See the language-specific READMEs for complete configuration, hOCR workflows, and inline image extraction.

Benchmarked on Apple M4 with complex real-world documents (Wikipedia articles, tables, lists):

• JavaScript bindings are fastest: Native Node.js bindings achieve ~18k ops/sec average, with WASM close behind at ~16k ops/sec
• Python is 6-10× slower: Despite using the same Rust core, PyO3 FFI overhead significantly impacts Python performance
• Small documents: Both JS implementations reach 70-90k ops/sec on simple HTML
• Large documents: Performance gap widens with complexity

Note on Python performance: The current Python bindings have optimization opportunities. The v2 API with direct convert() calls performs best; avoid the v1 compatibility layer for performance-critical applications.

• V2’s Rust core sustains 150–210 MB/s throughput; V1 averaged ≈ 2.5 MB/s in its Python/BeautifulSoup implementation (60–80× faster).
• The Python package offers a compatibility shim in html_to_markdown.v1_compat (convert_to_markdown, convert_to_markdown_stream, markdownify). Details and keyword mappings live in Python README.
• CLI flag changes, option renames, and other breaking updates are summarised in CHANGELOG.

• Chat with us on Discord
• Explore the broader Kreuzberg document-processing ecosystem
• Sponsor development via GitHub Sponsors

require 'html_to_markdown'

html = '<h1>Hello</h1><p>Rust ❤️ Markdown</p>'
markdown = HtmlToMarkdown.convert(html, heading_style: :atx, wrap: true)

puts markdown
# # Hello
#
# Rust ❤️ Markdown

See the language-specific READMEs for complete configuration, hOCR workflows, and inline image extraction.