@kreuzberg/html-to-markdown-node 2.19.0-rc.1

package/README.md

@@ -0,0 +1,350 @@
+# @kreuzberg/html-to-markdown-node
+
+> **npm package:** `@kreuzberg/html-to-markdown-node` (this README).
+> Use [`@kreuzberg/html-to-markdown-wasm`](https://www.npmjs.com/package/@kreuzberg/html-to-markdown-wasm) for the portable WASM build.
+
+Native Node.js and Bun bindings for html-to-markdown using NAPI-RS v3.
+
+Built on the shared Rust engine that powers the Python wheels, Ruby gem, PHP extension, WebAssembly package, and CLI – ensuring identical Markdown output across every language target.
+
+High-performance HTML to Markdown conversion using native Rust code compiled to platform-specific binaries.
+
+[![Crates.io](https://img.shields.io/crates/v/html-to-markdown-rs.svg?logo=rust&label=crates.io)](https://crates.io/crates/html-to-markdown-rs)
+[![npm (node)](https://img.shields.io/npm/v/%40kreuzberg%2Fhtml-to-markdown-node.svg?logo=npm)](https://www.npmjs.com/package/@kreuzberg/html-to-markdown-node)
+[![npm (wasm)](https://img.shields.io/npm/v/%40kreuzberg%2Fhtml-to-markdown-wasm.svg?logo=npm)](https://www.npmjs.com/package/@kreuzberg/html-to-markdown-wasm)
+[![PyPI](https://img.shields.io/pypi/v/html-to-markdown.svg?logo=pypi)](https://pypi.org/project/html-to-markdown/)
+[![Packagist](https://img.shields.io/packagist/v/goldziher/html-to-markdown.svg)](https://packagist.org/packages/goldziher/html-to-markdown)
+[![RubyGems](https://badge.fury.io/rb/html-to-markdown.svg)](https://rubygems.org/gems/html-to-markdown)
+[![NuGet](https://img.shields.io/nuget/v/Goldziher.HtmlToMarkdown.svg)](https://www.nuget.org/packages/Goldziher.HtmlToMarkdown/)
+[![Maven Central](https://img.shields.io/maven-central/v/io.github.goldziher/html-to-markdown.svg)](https://central.sonatype.com/artifact/io.github.goldziher/html-to-markdown)
+[![Go Reference](https://pkg.go.dev/badge/github.com/kreuzberg-dev/html-to-markdown/packages/go/v2/htmltomarkdown.svg)](https://pkg.go.dev/github.com/kreuzberg-dev/html-to-markdown/packages/go/v2/htmltomarkdown)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/kreuzberg-dev/html-to-markdown/blob/main/LICENSE)
+
+## Performance
+
+Native NAPI-RS bindings deliver **the fastest HTML to Markdown conversion** available in JavaScript.
+
+### Benchmark Results (Apple M4)
+
+| Document Type              | ops/sec    | Notes              |
+| -------------------------- | ---------- | ------------------ |
+| **Small (5 paragraphs)**   | **86,233** | Simple documents   |
+| **Medium (25 paragraphs)** | **18,979** | Nested formatting  |
+| **Large (100 paragraphs)** | **4,907**  | Complex structures |
+| **Tables (20 tables)**     | **5,003**  | Table processing   |
+| **Lists (500 items)**      | **1,819**  | Nested lists       |
+| **Wikipedia (129KB)**      | **1,125**  | Real-world content |
+| **Wikipedia (653KB)**      | **156**    | Large documents    |
+
+**Average: ~18,162 ops/sec** across varied workloads.
+
+### Comparison
+
+- **vs WASM**: ~1.17× faster (native has zero startup time, direct memory access)
+- **vs Python**: ~7.4× faster (avoids FFI overhead)
+- **Best for**: Node.js and Bun server-side applications requiring maximum throughput
+
+### Benchmark Fixtures (Apple M4)
+
+The shared benchmark harness lives in `tools/benchmark-harness`. Node keeps pace with the Rust CLI across the board:
+
+| Document               | Size   | ops/sec (Node) |
+| ---------------------- | ------ | -------------- |
+| Lists (Timeline)       | 129 KB | 3,137          |
+| Tables (Countries)     | 360 KB | 932            |
+| Medium (Python)        | 657 KB | 460            |
+| Large (Rust)           | 567 KB | 554            |
+| Small (Intro)          | 463 KB | 627            |
+| hOCR German PDF        | 44 KB  | 8,724          |
+| hOCR Invoice           | 4 KB   | 96,138         |
+| hOCR Embedded Tables   | 37 KB  | 9,591          |
+
+> Run `task bench:harness -- --frameworks node` to regenerate these numbers.
+
+## Installation
+
+### Node.js
+
+```bash
+npm install @kreuzberg/html-to-markdown-node
+# or
+yarn add @kreuzberg/html-to-markdown-node
+# or
+pnpm add @kreuzberg/html-to-markdown-node
+```
+
+### Bun
+
+```bash
+bun add @kreuzberg/html-to-markdown-node
+```
+
+## Usage
+
+### Basic Conversion
+
+```javascript
+import { convert } from '@kreuzberg/html-to-markdown-node';
+
+const html = '<h1>Hello World</h1><p>This is <strong>fast</strong>!</p>';
+const markdown = convert(html);
+console.log(markdown);
+// # Hello World
+//
+// This is **fast**!
+```
+
+### With Options
+
+```typescript
+import { convert } from '@kreuzberg/html-to-markdown-node';
+
+const markdown = convert(html, {
+  headingStyle: 'Atx',
+  codeBlockStyle: 'Backticks',
+  listIndentWidth: 2,
+  bullets: '-',
+  wrap: true,
+  wrapWidth: 80
+});
+```
+
+### Preserve Complex HTML (NEW in v2.5)
+
+```typescript
+import { convert } from '@kreuzberg/html-to-markdown-node';
+
+const html = `
+<h1>Report</h1>
+<table>
+  <tr><th>Name</th><th>Value</th></tr>
+  <tr><td>Foo</td><td>Bar</td></tr>
+</table>
+`;
+
+const markdown = convert(html, {
+  preserveTags: ['table'] // Keep tables as HTML
+});
+// # Report
+//
+// <table>
+//   <tr><th>Name</th><th>Value</th></tr>
+//   <tr><td>Foo</td><td>Bar</td></tr>
+// </table>
+```
+
+## TypeScript
+
+Full TypeScript definitions included:
+
+```typescript
+import { convert, convertWithInlineImages, type JsConversionOptions } from '@kreuzberg/html-to-markdown-node';
+
+const options: JsConversionOptions = {
+  headingStyle: 'Atx',
+  codeBlockStyle: 'Backticks',
+  listIndentWidth: 2,
+  bullets: '-',
+  wrap: true,
+  wrapWidth: 80
+};
+
+const markdown = convert('<h1>Hello</h1>', options);
+```
+
+### Reusing Parsed Options
+
+Avoid re-parsing the same options object on every call (benchmarks, tight render loops) by creating a reusable handle:
+
+```ts
+import {
+  createConversionOptionsHandle,
+  convertWithOptionsHandle,
+} from '@kreuzberg/html-to-markdown-node';
+
+const handle = createConversionOptionsHandle({ hocrSpatialTables: false });
+const markdown = convertWithOptionsHandle('<h1>Handles</h1>', handle);
+```
+
+### Zero-Copy Buffer Input
+
+Skip the intermediate UTF-16 string allocation by feeding `Buffer`/`Uint8Array` inputs directly—handy for benchmark harnesses or when you already have raw bytes:
+
+```ts
+import {
+  convertBuffer,
+  convertInlineImagesBuffer,
+  convertBufferWithOptionsHandle,
+  createConversionOptionsHandle,
+} from '@kreuzberg/html-to-markdown-node';
+import { readFileSync } from 'node:fs';
+
+const html = readFileSync('fixtures/lists.html'); // Buffer
+const markdown = convertBuffer(html);
+
+const handle = createConversionOptionsHandle({ headingStyle: 'Atx' });
+const markdownFromHandle = convertBufferWithOptionsHandle(html, handle);
+
+// Inline images work too:
+const extraction = convertInlineImagesBuffer(html, null, {
+  maxDecodedSizeBytes: 5 * 1024 * 1024,
+});
+```
+
+## Inline Images
+
+Extract and decode inline images (data URIs, SVG):
+
+```typescript
+import { convertWithInlineImages } from '@kreuzberg/html-to-markdown-node';
+
+const html = '<img src="data:image/png;base64,iVBORw0..." alt="Logo">';
+
+const result = convertWithInlineImages(html, null, {
+  maxDecodedSizeBytes: 5 * 1024 * 1024, // 5MB
+  inferDimensions: true,
+  filenamePrefix: 'img_',
+  captureSvg: true
+});
+
+console.log(result.markdown);
+console.log(`Extracted ${result.inlineImages.length} images`);
+
+for (const img of result.inlineImages) {
+  console.log(`${img.filename}: ${img.format}, ${img.data.length} bytes`);
+  // Save image data to disk
+  require('fs').writeFileSync(img.filename, img.data);
+}
+```
+
+## Supported Platforms
+
+Pre-built native binaries are provided for:
+
+| Platform    | Architectures                                       |
+| ----------- | --------------------------------------------------- |
+| **macOS**   | x64 (Intel), ARM64 (Apple Silicon)                  |
+| **Linux**   | x64 (glibc/musl), ARM64 (glibc/musl), ARMv7 (glibc) |
+| **Windows** | x64, ARM64                                          |
+
+### Runtime Compatibility
+
+✅ **Node.js** 18+ (LTS)
+✅ **Bun** 1.0+ (full NAPI-RS support)
+❌ **Deno** (use [@kreuzberg/html-to-markdown-wasm](https://www.npmjs.com/package/@kreuzberg/html-to-markdown-wasm) instead)
+
+## When to Use
+
+Choose `@kreuzberg/html-to-markdown-node` when:
+
+- ✅ Running in Node.js or Bun
+- ✅ Maximum performance is required
+- ✅ Server-side conversion at scale
+
+Use [`html-to-markdown-wasm`](https://www.npmjs.com/package/html-to-markdown-wasm) for:
+
+- 🌐 Browser/client-side conversion
+- 🦕 Deno runtime
+- ☁️ Edge runtimes (Cloudflare Workers, Deno Deploy)
+- 📦 Universal packages
+
+Other runtimes:
+
+- 🐍 Python: [`html-to-markdown`](https://pypi.org/project/html-to-markdown/)
+- 💎 Ruby: [`html-to-markdown`](https://rubygems.org/gems/html-to-markdown)
+- 🐘 PHP: [`goldziher/html-to-markdown`](https://packagist.org/packages/goldziher/html-to-markdown)
+- 🌐 WebAssembly: [`html-to-markdown-wasm`](https://www.npmjs.com/package/html-to-markdown-wasm)
+
+## Configuration Options
+
+See [ConversionOptions](https://github.com/kreuzberg-dev/html-to-markdown/tree/main/crates/html-to-markdown-node#types) for all available options including:
+
+- Heading styles (ATX, underlined, ATX closed)
+- Code block styles (indented, backticks, tildes)
+- List formatting (indent width, bullet characters)
+- Text escaping and formatting
+- Tag preservation (`preserveTags`) and stripping (`stripTags`)
+- Preprocessing for web scraping
+- hOCR table extraction
+- And more...
+
+## Examples
+
+### Preserving HTML Tags
+
+Keep specific HTML tags in their original form instead of converting to Markdown:
+
+```typescript
+import { convert } from '@kreuzberg/html-to-markdown-node';
+
+const html = `
+<p>Before table</p>
+<table class="data">
+    <tr><th>Name</th><th>Value</th></tr>
+    <tr><td>Item 1</td><td>100</td></tr>
+</table>
+<p>After table</p>
+`;
+
+const markdown = convert(html, {
+  preserveTags: ['table']
+});
+
+// Result includes the table as HTML:
+// "Before table\n\n<table class=\"data\">...</table>\n\nAfter table\n"
+```
+
+Combine with `stripTags` for fine-grained control:
+
+```typescript
+const markdown = convert(html, {
+  preserveTags: ['table', 'form'],  // Keep these as HTML
+  stripTags: ['script', 'style']    // Remove these entirely
+});
+```
+
+### Web Scraping
+
+```javascript
+const { convert } = require('@kreuzberg/html-to-markdown-node');
+
+const scrapedHtml = await fetch('https://example.com').then(r => r.text());
+
+const markdown = convert(scrapedHtml, {
+  preprocessing: {
+    enabled: true,
+    preset: 'Aggressive',
+    removeNavigation: true,
+    removeForms: true
+  },
+  headingStyle: 'Atx',
+  codeBlockStyle: 'Backticks'
+});
+```
+
+### hOCR Document Processing
+
+```javascript
+const { convert } = require('@kreuzberg/html-to-markdown-node');
+const fs = require('fs');
+
+// OCR output from Tesseract in hOCR format
+const hocrHtml = fs.readFileSync('scan.hocr', 'utf8');
+
+// Automatically detects hOCR and reconstructs tables
+const markdown = convert(hocrHtml, {
+  hocrSpatialTables: true  // Enable spatial table reconstruction
+});
+```
+
+## Links
+
+- [GitHub Repository](https://github.com/kreuzberg-dev/html-to-markdown)
+- [Full Documentation](https://github.com/kreuzberg-dev/html-to-markdown/blob/main/README.md)
+- [WASM Package](https://www.npmjs.com/package/html-to-markdown-wasm)
+- [Python Package](https://pypi.org/project/html-to-markdown/)
+- [Rust Crate](https://crates.io/crates/html-to-markdown-rs)
+
+## License
+
+MIT