![\"Built](\"https://img.shields.io/badge/built%20with-alef%20%D7%90-007ec6\"){kind=icon}
\n \n \n \n ![\"Rust\"](\"https://img.shields.io/crates/v/html-to-markdown-rs?label=Rust&color=007ec6\")
\n \n \n ![\"Python\"](\"https://img.shields.io/pypi/v/html-to-markdown?label=Python&color=007ec6\")
\n \n \n ![\"Node.js\"](\"https://img.shields.io/npm/v/@kreuzberg/html-to-markdown-node?label=Node.js&color=007ec6\")
\n \n \n ![\"WASM\"](\"https://img.shields.io/npm/v/@kreuzberg/html-to-markdown-wasm?label=WASM&color=007ec6\")
\n \n \n ![\"Java\"](\"https://img.shields.io/maven-central/v/dev.kreuzberg/html-to-markdown?label=Java&color=007ec6\")
\n \n \n ![\"Go\"](\"https://img.shields.io/github/v/tag/kreuzberg-dev/html-to-markdown?label=Go&color=007ec6&filter=v3*\")
\n \n \n ![\"C#\"](\"https://img.shields.io/nuget/v/KreuzbergDev.HtmlToMarkdown?label=C%23&color=007ec6\")
\n \n \n ![\"PHP\"](\"https://img.shields.io/packagist/v/kreuzberg-dev/html-to-markdown?label=PHP&color=007ec6\")
\n \n \n ![\"Ruby\"](\"https://img.shields.io/gem/v/html-to-markdown?label=Ruby&color=007ec6\")
\n \n \n ![\"Elixir\"](\"https://img.shields.io/hexpm/v/html_to_markdown?label=Elixir&color=007ec6\")
\n \n \n ![\"R\"](\"https://img.shields.io/badge/R-htmltomarkdown-007ec6\"){kind=icon}
\n \n \n ![\"Dart\"](\"https://img.shields.io/pub/v/h2m?label=Dart&color=007ec6\")
\n \n \n ![\"Kotlin\"](\"https://img.shields.io/maven-central/v/dev.kreuzberg/html-to-markdown-android?label=Kotlin&color=007ec6\")
\n \n \n ![\"Swift\"](\"https://img.shields.io/badge/Swift-SPM-007ec6\"){kind=icon}
\n \n \n ![\"Zig\"](\"https://img.shields.io/badge/Zig-package-007ec6\"){kind=icon}
\n \n \n ![\"C](\"https://img.shields.io/badge/C-FFI-007ec6\"){kind=icon}
\n \n\n \n \n ![\"License\"](\"https://img.shields.io/badge/License-MIT-007ec6\"){kind=icon}
\n \n \n ![\"Documentation\"](\"https://img.shields.io/badge/Docs-html--to--markdown-007ec6\"){kind=icon}
\n \nContent
\", options);\nconst markdown = result.content;\n```\n\n## Architecture\n\nThe converter routes each input through one of three tiers based on a fast prescan of the byte stream:\n\n1. **Tier-1 — single-pass byte scanner.** Handles 110+ HTML tags directly. Bails on any construct it cannot prove byte-equivalent to Tier-2.\n2. **Tier-2 — DOM walker.** Picks up Tier-1 bails and inputs the classifier rejected up front.\n3. **Tier-3 — standards-conformant parser.** Engaged for malformed HTML requiring full HTML5 repair.\n\nThe dispatcher is invisible to the caller. Output is byte-identical across tiers — enforced by a 116-snapshot oracle.\n\n## Capabilities\n\n- **16 languages, one Rust core.** Rust, Python, Node.js, WASM, Java, Go, C#, PHP, Ruby, Elixir, R, Dart, Kotlin (Android), Swift, Zig, C ABI.\n- **CommonMark-compatible Markdown** with GFM-style tables.\n- **Djot output**: set `output_format = \"djot\"` (see Djot Output Format section below).\n- **Real-HTML robust**: unclosed tags, CDATA, custom elements, malformed entities, nested tables, mixed encodings handled without losing content.\n- **Metadata extraction**, **visitor API**, **inline images**, **configurable preprocessing presets**.\n- **Per-group regression gates in CI**: every PR runs the bench harness against per-group thresholds.\n\n## API Reference\n\n### Core Function\n\n**`convert(html: string, options?: ConversionOptions, visitor?: Visitor): ConversionResult`**\n\nConverts HTML to Markdown. Returns a `ConversionResult` object with all results in a single call.\n\n```typescript\nimport { convert, ConversionOptions } from \"@kreuzberg/html-to-markdown\";\n\nconst result = convert(html);\nconst markdown = result.content; // Converted Markdown string\nconst metadata = result.metadata; // Metadata (when extractMetadata: true)\nconst tables = result.tables; // Structured table data\nconst document = result.document; // Document-level info\nconst images = result.images; // Extracted images\nconst warnings = result.warnings; // Any conversion warnings\n```\n\n### Options\n\n**`ConversionOptions`** – Key configuration fields:\n\n- `heading_style`: Heading format (`\"underlined\"` | `\"atx\"` | `\"atx_closed\"`) — default: `\"atx\"`\n- `list_indent_width`: Spaces per indent level — default: `2`\n- `bullets`: Bullet characters cycle — default: `\"-*+\"`\n- `wrap`: Enable text wrapping — default: `false`\n- `wrap_width`: Wrap at column — default: `80`\n- `code_language`: Default fenced code block language — default: none\n- `extract_metadata`: Enable metadata extraction into `result.metadata` — default: `true`\n- `output_format`: Output markup format (`\"markdown\"` | `\"djot\"` | `\"plain\"`) — default: `\"markdown\"`\n\n## Djot Output Format\n\nThe library supports converting HTML to [Djot](https://djot.net/), a lightweight markup language similar to Markdown but with a different syntax for some elements. Set `output_format` to `\"djot\"` to use this format.\n\n### Syntax Differences\n\n| Element | Markdown | Djot |\n| -------------- | ---------- | ---------- |\n| Strong | `**text**` | `*text*` |\n| Emphasis | `*text*` | `_text_` |\n| Strikethrough | `~~text~~` | `{-text-}` |\n| Inserted/Added | N/A | `{+text+}` |\n| Highlighted | N/A | `{=text=}` |\n| Subscript | N/A | `~text~` |\n| Superscript | N/A | `^text^` |\n\n### Example Usage\n\n```typescript\nimport { convert, OutputFormat } from \"@kreuzberg/html-to-markdown\";\n\nconst html = \"This is bold and italic text.
\";\n\n// Default Markdown output\nconst markdownResult = convert(html);\nconst markdown = markdownResult.content;\n// Result: \"This is **bold** and *italic* text.\"\n\n// Djot output\nconst djotResult = convert(html, { outputFormat: OutputFormat.Djot });\nconst djot = djotResult.content;\n// Result: \"This is *bold* and _italic_ text.\"\n```\n\nDjot's extended syntax allows you to express more semantic meaning in lightweight text, making it useful for documents that require strikethrough, insertion tracking, or mathematical notation.\n\n## Plain Text Output\n\nSet `output_format` to `\"plain\"` to strip all markup and return only visible text. This bypasses the Markdown conversion pipeline entirely for maximum speed.\n\n```typescript\nimport { convert, OutputFormat } from \"@kreuzberg/html-to-markdown\";\n\nconst html = \"This is bold and italic text.
\";\n\nconst result = convert(html, { outputFormat: OutputFormat.Plain });\nconst plain = result.content;\n// Result: \"Title\\n\\nThis is bold and italic text.\"\n```\n\nPlain text mode is useful for search indexing, text extraction, and feeding content to LLMs.\n\n## Metadata Extraction\n\nThe metadata extraction feature enables comprehensive document analysis during conversion. Extract document properties, headers, links, images, and structured data in a single pass — all via the standard `convert()` function.\n\n**Use Cases:**\n\n- **SEO analysis** – Extract title, description, Open Graph tags, Twitter cards\n- **Table of contents generation** – Build structured outlines from heading hierarchy\n- **Content migration** – Document all external links and resources\n- **Accessibility audits** – Check for images without alt text, empty links, invalid heading hierarchy\n- **Link validation** – Classify and validate anchor, internal, external, email, and phone links\n\n**Zero Overhead When Disabled:** Metadata extraction adds negligible overhead and happens during the HTML parsing pass. Pass `extract_metadata: true` in `ConversionOptions` to enable it; the result is available at `result.metadata`.\n\n### Example: Quick Start\n\n```typescript\nimport { convert } from \"@kreuzberg/html-to-markdown\";\n\nconst html = '![\"test\"](\"test.jpg\")
';\nconst result = convert(html, { extractMetadata: true });\n\nconsole.log(result.content); // Converted Markdown\nconsole.log(result.metadata?.document?.title); // Document title\nconsole.log(result.metadata?.headers); // All h1-h6 elements\nconsole.log(result.metadata?.links); // All hyperlinks\nconsole.log(result.metadata?.images); // All images with alt text\nconsole.log(result.metadata?.structuredData); // JSON-LD, Microdata, RDFa\n```\n\n## Visitor Pattern\n\nThe visitor pattern enables custom HTML→Markdown conversion logic by providing callbacks for specific HTML elements during traversal. Pass a visitor as the third argument to `convert()`.\n\n**Use Cases:**\n\n- **Custom Markdown dialects** – Convert to Obsidian, Notion, or other flavors\n- **Content filtering** – Remove tracking pixels, ads, or unwanted elements\n- **URL rewriting** – Rewrite CDN URLs, add query parameters, validate links\n- **Accessibility validation** – Check alt text, heading hierarchy, link text\n- **Analytics** – Track element usage, link destinations, image sources\n\n**Supported Visitor Methods:** 40+ callbacks for text, inline elements, links, images, headings, lists, blocks, and tables.\n\n### Example: Quick Start\n\n```typescript\nimport {\n convert,\n type Visitor,\n type NodeContext,\n type VisitResult,\n} from \"@kreuzberg/html-to-markdown\";\n\nconst visitor: Visitor = {\n visitLink(ctx: NodeContext, href: string, text: string, title?: string): VisitResult {\n // Rewrite CDN URLs\n if (href.startsWith(\"https://old-cdn.com\")) {\n href = href.replace(\"https://old-cdn.com\", \"https://new-cdn.com\");\n }\n return { type: \"custom\", output: `[${text}](${href})` };\n },\n\n visitImage(ctx: NodeContext, src: string, alt?: string, title?: string): VisitResult {\n // Skip tracking pixels\n if (src.includes(\"tracking\")) {\n return { type: \"skip\" };\n }\n return { type: \"continue\" };\n },\n};\n\nconst html = 'Download';\nconst result = convert(html, {}, visitor);\nconst markdown = result.content;\n```\n\n## Examples\n\n## Links\n\n- **GitHub:** [github.com/kreuzberg-dev/html-to-markdown](https://github.com/kreuzberg-dev/html-to-markdown)\n- **npm:** [npmjs.com/@kreuzberg/html-to-markdown](https://www.npmjs.com/package/@kreuzberg/html-to-markdown-node)\n- **WASM:** [npmjs.com/@kreuzberg/html-to-markdown-wasm](https://www.npmjs.com/package/@kreuzberg/html-to-markdown-wasm)\n- **Discord:** [discord.gg/xt9WY3GnKR](https://discord.gg/xt9WY3GnKR)\n\n## Part of Kreuzberg.dev\n\n- [Kreuzberg](https://github.com/kreuzberg-dev/kreuzberg) — document intelligence: text, tables, metadata from 91+ formats with optional OCR.\n- [Kreuzberg Cloud](https://github.com/kreuzberg-dev/kreuzberg-cloud) — managed extraction API with SDKs, dashboards, and observability.\n- [kreuzcrawl](https://github.com/kreuzberg-dev/kreuzcrawl) — web crawling and scraping with HTML→Markdown and headless-Chrome fallback.\n- [html-to-markdown](https://github.com/kreuzberg-dev/html-to-markdown) — fast, lossless HTML→Markdown engine.\n- [liter-llm](https://github.com/kreuzberg-dev/liter-llm) — universal LLM API client with native bindings for 14 languages and 143 providers.\n- [tree-sitter-language-pack](https://github.com/kreuzberg-dev/tree-sitter-language-pack) — tree-sitter grammars and code-intelligence primitives.\n- [alef](https://github.com/kreuzberg-dev/alef) — the polyglot binding generator that produces every per-language binding across the 5 polyglot repos.\n\n## Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](https://github.com/kreuzberg-dev/html-to-markdown/blob/main/CONTRIBUTING.md) for details on:\n\n- Setting up the development environment\n- Running tests locally\n- Submitting pull requests\n- Reporting issues\n\nAll contributions must follow our code quality standards (enforced via pre-commit hooks):\n\n- Proper test coverage (Rust 95%+, language bindings 80%+)\n- Formatting and linting checks\n- Documentation for public APIs\n\n## License\n\nMIT License – see [LICENSE](https://github.com/kreuzberg-dev/html-to-markdown/blob/main/LICENSE). Copyright © Kreuzberg, Inc.\n\n## Support\n\nIf you find this library useful, consider [sponsoring the project](https://github.com/sponsors/kreuzberg-dev).\n\nHave questions or run into issues? We're here to help:\n\n- **GitHub Issues:** [github.com/kreuzberg-dev/html-to-markdown/issues](https://github.com/kreuzberg-dev/html-to-markdown/issues)\n- **Discord Community:** [discord.gg/xt9WY3GnKR](https://discord.gg/xt9WY3GnKR)\n","readmeFilename":"README.md"}![\"Join](\"https://img.shields.io/badge/Discord-Chat-007ec6?logo=discord&logoColor=white\"){kind=icon}
\n ![\"Live](\"https://img.shields.io/badge/Live%20Demo-Open-007ec6?logo=webassembly&logoColor=white\"){kind=icon}
\n