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

package/README.md

@@ -0,0 +1,350 @@
+# html-to-markdown (TypeScript)
+
+[![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)
+[![Hex.pm](https://img.shields.io/hexpm/v/html_to_markdown.svg)](https://hex.pm/packages/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)
+[![Discord](https://img.shields.io/badge/Discord-Join%20our%20community-7289da)](https://discord.gg/pXxagNK2zN)
+
+High-performance HTML to Markdown converter for Node.js and Bun with full TypeScript support. This package wraps native `@kreuzberg/html-to-markdown-node` bindings and provides a type-safe API.
+
+## Installation
+
+```bash
+# Native bindings (Node.js/Bun) - Recommended
+npm install @kreuzberg/html-to-markdown
+pnpm add @kreuzberg/html-to-markdown
+yarn add @kreuzberg/html-to-markdown
+bun add @kreuzberg/html-to-markdown
+
+# WebAssembly (browser/edge/Node without native toolchain)
+npm install @kreuzberg/html-to-markdown-wasm
+```
+
+## Migration Guide (v2.18.x → v2.19.0)
+
+### Breaking Change: Scoped npm Packages
+
+In v2.19.0, npm packages were moved to the `@kreuzberg` scope to align with the Kreuzberg.dev organization.
+
+#### Package Installation Update
+
+**Before (v2.18.x):**
+```bash
+npm install html-to-markdown-node
+npm install html-to-markdown-wasm
+```
+
+**After (v2.19.0+):**
+```bash
+npm install @kreuzberg/html-to-markdown-node
+npm install @kreuzberg/html-to-markdown-wasm
+```
+
+#### Import Statement Update
+
+**Before:**
+```typescript
+import { convert } from 'html-to-markdown-node';
+import { convert } from 'html-to-markdown-wasm';
+```
+
+**After:**
+```typescript
+import { convert } from '@kreuzberg/html-to-markdown-node';
+import { convert } from '@kreuzberg/html-to-markdown-wasm';
+```
+
+#### TypeScript Declaration Update
+
+Update your TypeScript configuration if you have imports from the old package name:
+
+**Before (tsconfig.json or import aliases):**
+```json
+{
+  "compilerOptions": {
+    "paths": {
+      "html-to-markdown": ["node_modules/html-to-markdown-node"]
+    }
+  }
+}
+```
+
+**After:**
+```json
+{
+  "compilerOptions": {
+    "paths": {
+      "@kreuzberg/html-to-markdown": ["node_modules/@kreuzberg/html-to-markdown-node"]
+    }
+  }
+}
+```
+
+#### Deno Update
+
+**Before:**
+```typescript
+import { convert } from "npm:html-to-markdown-wasm";
+```
+
+**After:**
+```typescript
+import { convert } from "npm:@kreuzberg/html-to-markdown-wasm";
+```
+
+#### Summary of Changes
+
+- All npm packages now use `@kreuzberg` scope
+- `html-to-markdown-node` → `@kreuzberg/html-to-markdown-node`
+- `html-to-markdown-wasm` → `@kreuzberg/html-to-markdown-wasm`
+- TypeScript types and APIs are identical
+- No functional changes to the library
+
+## Quick Start
+
+**Basic conversion with type safety:**
+```typescript
+import { convert } from '@kreuzberg/html-to-markdown';
+
+const markdown: string = convert('<h1>Hello World</h1>');
+console.log(markdown); // # Hello World
+```
+
+**With conversion options:**
+```typescript
+import { convert, ConversionOptions } from '@kreuzberg/html-to-markdown';
+
+const options: ConversionOptions = {
+  headingStyle: 'atx',
+  listIndentWidth: 2,
+  wrap: true,
+};
+
+const markdown = convert('<h1>Title</h1><p>Content</p>', options);
+```
+
+**TypeScript interfaces for type safety:**
+```typescript
+interface ConversionOptions {
+  headingStyle?: 'atx' | 'setext';
+  listIndentWidth?: number;
+  wrap?: boolean;
+  wrapWidth?: number;
+  // ... more options
+}
+```
+
+**File and stream helpers:**
+```typescript
+import { convertFile, convertBuffer } from '@kreuzberg/html-to-markdown';
+
+// From file
+const markdown = await convertFile('page.html');
+
+// From Buffer/Uint8Array
+const buffer = Buffer.from('<h1>Title</h1>');
+const markdown = convertBuffer(buffer);
+```
+
+## API Reference
+
+### Core Functions
+
+#### `convert(html: string, options?: ConversionOptions): string`
+Convert HTML string to Markdown.
+
+#### `convertBuffer(buffer: Buffer | Uint8Array, options?: ConversionOptions): string`
+Convert HTML from Buffer/Uint8Array (avoids string allocation overhead).
+
+#### `convertFile(filePath: string, options?: ConversionOptions): Promise<string>`
+Asynchronously convert an HTML file to Markdown.
+
+#### `convertStream(stream: NodeJS.ReadableStream, options?: ConversionOptions): Promise<string>`
+Convert HTML from a readable stream (stdin, file stream, network).
+
+### Metadata Extraction Functions
+
+Requires `metadata` feature flag.
+
+#### `convertWithMetadata(html: string, options?, metadataConfig?): { markdown: string; metadata: JsExtendedMetadata }`
+Convert and extract document metadata, headers, links, images, and structured data.
+
+#### `convertWithMetadataBuffer(buffer: Buffer | Uint8Array, options?, metadataConfig?): JsMetadataExtraction`
+Convert from Buffer with metadata extraction.
+
+#### `convertFileWithMetadata(filePath: string, options?, metadataConfig?): Promise<JsMetadataExtraction>`
+Convert HTML file with metadata extraction.
+
+#### `convertStreamWithMetadata(stream: NodeJS.ReadableStream, options?, metadataConfig?): Promise<JsMetadataExtraction>`
+Convert stream with metadata extraction.
+
+#### `hasMetadataSupport(): boolean`
+Check if metadata extraction is available at runtime.
+
+### Visitor Pattern Functions
+
+Custom element callbacks for fine-grained conversion control.
+
+#### `convertWithVisitor(html: string, config: { visitor: Visitor; options?: ConversionOptions }): string | Promise<string>`
+Convert with visitor callbacks for element interception.
+
+#### `convertWithAsyncVisitor(html: string, config: { visitor: AsyncVisitor; options?: ConversionOptions }): Promise<string>`
+Convert with async visitor methods for I/O operations.
+
+## Type Definitions
+
+### ConversionOptions
+```typescript
+interface ConversionOptions {
+  headingStyle?: 'atx' | 'setext';           // # Style or underline style
+  bulletListMarker?: '-' | '*' | '+';        // List marker
+  codeBlockStyle?: 'fenced' | 'indented';    // Code block format
+  horizontalRule?: string;                   // --- or *** or ___
+  listIndentWidth?: number;                  // Indentation (default: 4)
+  wrap?: boolean;                            // Enable text wrapping
+  wrapWidth?: number;                        // Wrap column width
+  preserveNotices?: boolean;                 // Keep HTML comments
+  sanitize?: boolean;                        // Remove unsafe HTML (default: true)
+  headingPrefix?: string;                    // Prefix for headings
+  strongDelimiter?: string;                  // ** or __
+  emDelimiter?: string;                      // * or _
+}
+```
+
+### Metadata Types
+```typescript
+interface JsMetadataConfig {
+  extractHeaders?: boolean;              // h1-h6 elements
+  extractLinks?: boolean;                // <a> elements
+  extractImages?: boolean;               // <img> and inline SVG
+  extractStructuredData?: boolean;       // JSON-LD, Microdata, RDFa
+  maxStructuredDataSize?: number;        // Size limit (default: 1MB)
+}
+
+interface JsExtendedMetadata {
+  document: JsDocumentMetadata;
+  headers: JsHeaderMetadata[];
+  links: JsLinkMetadata[];
+  images: JsImageMetadata[];
+  structuredData: JsStructuredData[];
+}
+
+interface JsDocumentMetadata {
+  title?: string;
+  description?: string;
+  keywords: string[];
+  author?: string;
+  canonicalUrl?: string;
+  language?: string;
+  textDirection?: 'ltr' | 'rtl' | 'auto';
+  openGraph: Record<string, string>;
+  twitterCard: Record<string, string>;
+  metaTags: Record<string, string>;
+}
+```
+
+### Visitor Types
+```typescript
+interface Visitor {
+  visitText?(ctx: NodeContext, text: string): VisitResult;
+  visitLink?(ctx: NodeContext, href: string, text: string, title?: string): VisitResult;
+  visitImage?(ctx: NodeContext, src: string, alt?: string, title?: string): VisitResult;
+  visitHeading?(ctx: NodeContext, level: number, text: string, id?: string): VisitResult;
+  visitCodeBlock?(ctx: NodeContext, lang?: string, code?: string): VisitResult;
+  // ... 41 total methods for fine-grained control
+}
+
+interface NodeContext {
+  nodeType: string;
+  tagName: string;
+  attributes: Record<string, string>;
+  depth: number;
+  indexInParent: number;
+  parentTag: string | null;
+  isInline: boolean;
+}
+
+type VisitResult =
+  | { type: 'continue' }
+  | { type: 'custom'; output: string }
+  | { type: 'skip' }
+  | { type: 'preserveHtml' }
+  | { type: 'error'; message: string };
+```
+
+## Error Handling
+
+```typescript
+try {
+  const markdown = convert(html);
+} catch (error) {
+  if (error instanceof Error) {
+    console.error('Conversion failed:', error.message);
+  }
+}
+```
+
+Inputs with binary data (PDF bytes coerced to strings) raise errors with message: `Invalid input`.
+
+## Examples
+
+See comprehensive guides in the examples directory:
+
+- **[Visitor Pattern](../../examples/visitor-pattern/)** - Custom callbacks, filtering, transformations, analytics
+- **[Metadata Extraction](../../examples/metadata-extraction/)** - SEO metadata, TOC generation, link validation
+- **[Performance](../../examples/performance/)** - Benchmarks, optimization strategies
+
+## TypeScript Configuration
+
+For strict type checking:
+
+```json
+{
+  "compilerOptions": {
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "noImplicitAny": true,
+    "noImplicitThis": true,
+    "strictNullChecks": true,
+    "strictFunctionTypes": true,
+    "strictPropertyInitialization": true,
+    "noImplicitReturns": true
+  }
+}
+```
+
+All bindings are fully typed with no `any` types. Leverage TypeScript for compile-time safety.
+
+## Performance
+
+Benchmarks from Apple M4 (ops/sec):
+
+| Document            | Size    | ops/sec |
+| ------------------- | ------- | ------- |
+| Small (Intro)       | 463 KB  | 627     |
+| Medium (Python)     | 657 KB  | 460     |
+| Large (Rust)        | 567 KB  | 554     |
+| Lists (Timeline)    | 129 KB  | 3,137   |
+| Tables (Countries)  | 360 KB  | 932     |
+
+Run `task bench:harness -- --frameworks node` to benchmark locally.
+
+## Links
+
+- [GitHub](https://github.com/kreuzberg-dev/html-to-markdown)
+- [npm Package](https://www.npmjs.com/package/@kreuzberg/html-to-markdown)
+- [WASM Package](https://www.npmjs.com/package/@kreuzberg/html-to-markdown-wasm)
+- [Discord Community](https://discord.gg/pXxagNK2zN)
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+import { promises as fs } from "node:fs";
+import { stderr, stdin, stdout } from "node:process";
+import { convertJson as convertHtmlJson, convertWithInlineImagesJson, } from "@kreuzberg/html-to-markdown-node";
+import { convertStream, convertStreamWithInlineImages } from "./index";
+const jsonReplacer = (_key, value) => (typeof value === "bigint" ? Number(value) : value);
+const toJson = (value) => {
+    if (value == null) {
+        return undefined;
+    }
+    return JSON.stringify(value, jsonReplacer);
+};
+function printUsage() {
+    stdout.write(`html-to-markdown CLI\n\n`);
+    stdout.write(`Usage:\n`);
+    stdout.write(`  html-to-markdown [--input <file>] [--output <file>] [--options '{...}'] [--inline-images]\n\n`);
+    stdout.write(`Options:\n`);
+    stdout.write(`  --input <file>           Read HTML from a file instead of stdin\n`);
+    stdout.write(`  --output <file>          Write Markdown to a file instead of stdout\n`);
+    stdout.write(`  --options <json>         JSON encoded conversion options\n`);
+    stdout.write(`  --inline-images          Collect inline images (writes JSON to <output>.images.json)\n`);
+    stdout.write(`  --inline-image-config    JSON encoded inline image extraction options\n`);
+    stdout.write(`  -h, --help               Show this help message\n`);
+    stdout.write(`  -v, --version            Print the package version\n`);
+}
+async function loadJson(value, label) {
+    try {
+        return JSON.parse(value);
+    }
+    catch (error) {
+        throw new Error(`Failed to parse ${label} JSON: ${error.message}`);
+    }
+}
+function getNextArg(args, index, flagName) {
+    const value = args[index + 1];
+    if (value === undefined) {
+        throw new Error(`Missing value for ${flagName}`);
+    }
+    return value;
+}
+async function parseArgs() {
+    const args = process.argv.slice(2);
+    const opts = {};
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === undefined)
+            continue;
+        switch (arg) {
+            case "-h":
+            case "--help":
+                return "help";
+            case "-v":
+            case "--version":
+                return "version";
+            case "--input":
+                opts.input = getNextArg(args, index, "--input");
+                index += 1;
+                break;
+            case "--output":
+                opts.output = getNextArg(args, index, "--output");
+                index += 1;
+                break;
+            case "--options":
+                opts.options = await loadJson(getNextArg(args, index, "--options"), "--options");
+                index += 1;
+                break;
+            case "--inline-images":
+                opts.inlineImages = true;
+                break;
+            case "--inline-image-config":
+                opts.inlineImageConfig = await loadJson(getNextArg(args, index, "--inline-image-config"), "--inline-image-config");
+                index += 1;
+                break;
+            default:
+                throw new Error(`Unknown argument: ${arg}`);
+        }
+    }
+    return opts;
+}
+async function readInput(path) {
+    if (path) {
+        return fs.readFile(path, "utf8");
+    }
+    if (!stdin.isTTY) {
+        return stdin;
+    }
+    throw new Error("No input provided. Pass --input <file> or pipe HTML via stdin.");
+}
+async function writeOutput(content, path) {
+    if (!path) {
+        stdout.write(content);
+        if (!content.endsWith("\n")) {
+            stdout.write("\n");
+        }
+        return;
+    }
+    await fs.writeFile(path, content, "utf8");
+}
+async function writeInlineImages(extractionPath, inlineData) {
+    const payload = {
+        markdown: inlineData.markdown,
+        inlineImages: inlineData.inlineImages,
+        warnings: inlineData.warnings,
+    };
+    await fs.writeFile(extractionPath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+}
+async function main() {
+    try {
+        const parsed = await parseArgs();
+        if (parsed === "help") {
+            printUsage();
+            return;
+        }
+        if (parsed === "version") {
+            const { version } = require("../package.json");
+            stdout.write(`${version}\n`);
+            return;
+        }
+        const { input, output, options, inlineImages, inlineImageConfig } = parsed;
+        const inputContent = await readInput(input);
+        if (inlineImages) {
+            const inlineResult = typeof inputContent === "string"
+                ? convertWithInlineImagesJson(inputContent, toJson(options), toJson(inlineImageConfig))
+                : await convertStreamWithInlineImages(inputContent, options, inlineImageConfig);
+            if (output) {
+                await writeOutput(inlineResult.markdown, output);
+                const imagePath = `${output}.images.json`;
+                await writeInlineImages(imagePath, inlineResult);
+                stdout.write(`Inline images written to ${imagePath}\n`);
+            }
+            else {
+                stdout.write(inlineResult.markdown);
+                if (!inlineResult.markdown.endsWith("\n")) {
+                    stdout.write("\n");
+                }
+                stdout.write(`${JSON.stringify({ inlineImages: inlineResult.inlineImages, warnings: inlineResult.warnings }, null, 2)}\n`);
+            }
+        }
+        else if (typeof inputContent === "string") {
+            const markdown = convertHtmlJson(inputContent, toJson(options));
+            await writeOutput(markdown, output);
+        }
+        else {
+            const markdown = await convertStream(inputContent, options);
+            await writeOutput(markdown, output);
+        }
+    }
+    catch (error) {
+        stderr.write(`Error: ${error.message}\n`);
+        process.exitCode = 1;
+    }
+}
+void main();

package/dist/index.d.ts

@@ -0,0 +1,80 @@
+import type { Readable } from "node:stream";
+import { type JsConversionOptions, type JsHtmlExtraction, type JsInlineImageConfig, type JsMetadataConfig, type JsMetadataExtraction } from "@kreuzberg/html-to-markdown-node";
+export * from "@kreuzberg/html-to-markdown-node";
+/**
+ * Check if metadata extraction functionality is available.
+ *
+ * @returns true if convertWithMetadata is available, false otherwise
+ */
+export declare function hasMetadataSupport(): boolean;
+/**
+ * Convert the contents of an HTML file to Markdown.
+ */
+export declare function convertFile(filePath: string, options?: JsConversionOptions | null | undefined): Promise<string>;
+/**
+ * Convert an HTML file and collect inline images.
+ */
+export declare function convertFileWithInlineImages(filePath: string, options?: JsConversionOptions | null | undefined, imageConfig?: JsInlineImageConfig | null | undefined): Promise<JsHtmlExtraction>;
+/**
+ * Convert HTML streamed from stdin or another readable stream.
+ */
+export declare function convertStream(stream: Readable | AsyncIterable<string | Buffer>, options?: JsConversionOptions | null | undefined): Promise<string>;
+/**
+ * Convert HTML from a stream and collect inline images.
+ */
+export declare function convertStreamWithInlineImages(stream: Readable | AsyncIterable<string | Buffer>, options?: JsConversionOptions | null | undefined, imageConfig?: JsInlineImageConfig | null | undefined): Promise<JsHtmlExtraction>;
+/**
+ * Convert HTML to Markdown and extract comprehensive metadata.
+ *
+ * Extracts document metadata (title, description, language, etc.), headers,
+ * links, images, and structured data (JSON-LD, Microdata, RDFa).
+ *
+ * @param html HTML content to convert
+ * @param options Optional conversion configuration
+ * @param metadataConfig Optional metadata extraction configuration
+ * @returns Object with converted markdown and extracted metadata
+ *
+ * @example
+ * ```ts
+ * import { convertWithMetadata } from 'html-to-markdown';
+ *
+ * const html = `
+ *   <html lang="en">
+ *     <head>
+ *       <title>My Article</title>
+ *       <meta name="description" content="An interesting article">
+ *     </head>
+ *     <body>
+ *       <h1>Main Title</h1>
+ *       <p>Content with <a href="/page">link</a></p>
+ *     </body>
+ *   </html>
+ * `;
+ *
+ * const { markdown, metadata } = await convertWithMetadata(html, undefined, {
+ *   extractHeaders: true,
+ *   extractLinks: true,
+ *   extractImages: true,
+ * });
+ *
+ * console.log(metadata.document.title);    // "My Article"
+ * console.log(metadata.headers.length);    // 1
+ * console.log(metadata.links.length);      // 1
+ * ```
+ */
+export declare function convertWithMetadata(html: string, options?: JsConversionOptions | null | undefined, metadataConfig?: JsMetadataConfig | null | undefined): JsMetadataExtraction;
+/**
+ * Convert HTML from Buffer/Uint8Array to Markdown with metadata extraction.
+ *
+ * Avoids creating intermediate JavaScript strings by accepting raw bytes.
+ * Auto-detects UTF-8 encoding.
+ */
+export declare function convertWithMetadataBuffer(html: Buffer | Uint8Array, options?: JsConversionOptions | null | undefined, metadataConfig?: JsMetadataConfig | null | undefined): JsMetadataExtraction;
+/**
+ * Convert the contents of an HTML file to Markdown with metadata extraction.
+ */
+export declare function convertFileWithMetadata(filePath: string, options?: JsConversionOptions | null | undefined, metadataConfig?: JsMetadataConfig | null | undefined): Promise<JsMetadataExtraction>;
+/**
+ * Convert HTML streamed from stdin or another readable stream with metadata extraction.
+ */
+export declare function convertStreamWithMetadata(stream: Readable | AsyncIterable<string | Buffer>, options?: JsConversionOptions | null | undefined, metadataConfig?: JsMetadataConfig | null | undefined): Promise<JsMetadataExtraction>;

package/dist/index.js

@@ -0,0 +1,126 @@
+import { readFile } from "node:fs/promises";
+import { convertJson as convertHtmlJson, convertWithInlineImagesJson as convertHtmlWithInlineImagesJson, convertWithMetadataBufferJson as convertHtmlWithMetadataBufferJson, convertWithMetadataJson as convertHtmlWithMetadataJson, } from "@kreuzberg/html-to-markdown-node";
+export * from "@kreuzberg/html-to-markdown-node";
+const jsonReplacer = (_key, value) => (typeof value === "bigint" ? Number(value) : value);
+const toJson = (value) => {
+    if (value == null) {
+        return undefined;
+    }
+    return JSON.stringify(value, jsonReplacer);
+};
+/**
+ * Check if metadata extraction functionality is available.
+ *
+ * @returns true if convertWithMetadata is available, false otherwise
+ */
+export function hasMetadataSupport() {
+    try {
+        return typeof convertHtmlWithMetadataJson === "function";
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Convert the contents of an HTML file to Markdown.
+ */
+export async function convertFile(filePath, options) {
+    const html = await readFile(filePath, "utf8");
+    return convertHtmlJson(html, toJson(options ?? undefined));
+}
+/**
+ * Convert an HTML file and collect inline images.
+ */
+export async function convertFileWithInlineImages(filePath, options, imageConfig) {
+    const html = await readFile(filePath, "utf8");
+    return convertHtmlWithInlineImagesJson(html, toJson(options ?? undefined), toJson(imageConfig ?? undefined));
+}
+/**
+ * Convert HTML streamed from stdin or another readable stream.
+ */
+export async function convertStream(stream, options) {
+    let html = "";
+    for await (const chunk of stream) {
+        html += typeof chunk === "string" ? chunk : chunk.toString("utf8");
+    }
+    return convertHtmlJson(html, toJson(options ?? undefined));
+}
+/**
+ * Convert HTML from a stream and collect inline images.
+ */
+export async function convertStreamWithInlineImages(stream, options, imageConfig) {
+    let html = "";
+    for await (const chunk of stream) {
+        html += typeof chunk === "string" ? chunk : chunk.toString("utf8");
+    }
+    return convertHtmlWithInlineImagesJson(html, toJson(options ?? undefined), toJson(imageConfig ?? undefined));
+}
+/**
+ * Convert HTML to Markdown and extract comprehensive metadata.
+ *
+ * Extracts document metadata (title, description, language, etc.), headers,
+ * links, images, and structured data (JSON-LD, Microdata, RDFa).
+ *
+ * @param html HTML content to convert
+ * @param options Optional conversion configuration
+ * @param metadataConfig Optional metadata extraction configuration
+ * @returns Object with converted markdown and extracted metadata
+ *
+ * @example
+ * ```ts
+ * import { convertWithMetadata } from 'html-to-markdown';
+ *
+ * const html = `
+ *   <html lang="en">
+ *     <head>
+ *       <title>My Article</title>
+ *       <meta name="description" content="An interesting article">
+ *     </head>
+ *     <body>
+ *       <h1>Main Title</h1>
+ *       <p>Content with <a href="/page">link</a></p>
+ *     </body>
+ *   </html>
+ * `;
+ *
+ * const { markdown, metadata } = await convertWithMetadata(html, undefined, {
+ *   extractHeaders: true,
+ *   extractLinks: true,
+ *   extractImages: true,
+ * });
+ *
+ * console.log(metadata.document.title);    // "My Article"
+ * console.log(metadata.headers.length);    // 1
+ * console.log(metadata.links.length);      // 1
+ * ```
+ */
+export function convertWithMetadata(html, options, metadataConfig) {
+    return convertHtmlWithMetadataJson(html, toJson(options ?? undefined), toJson(metadataConfig ?? undefined));
+}
+/**
+ * Convert HTML from Buffer/Uint8Array to Markdown with metadata extraction.
+ *
+ * Avoids creating intermediate JavaScript strings by accepting raw bytes.
+ * Auto-detects UTF-8 encoding.
+ */
+export function convertWithMetadataBuffer(html, options, metadataConfig) {
+    const input = Buffer.isBuffer(html) ? html : Buffer.from(html);
+    return convertHtmlWithMetadataBufferJson(input, toJson(options ?? undefined), toJson(metadataConfig ?? undefined));
+}
+/**
+ * Convert the contents of an HTML file to Markdown with metadata extraction.
+ */
+export async function convertFileWithMetadata(filePath, options, metadataConfig) {
+    const html = await readFile(filePath, "utf8");
+    return convertWithMetadata(html, options ?? undefined, metadataConfig ?? undefined);
+}
+/**
+ * Convert HTML streamed from stdin or another readable stream with metadata extraction.
+ */
+export async function convertStreamWithMetadata(stream, options, metadataConfig) {
+    let html = "";
+    for await (const chunk of stream) {
+        html += typeof chunk === "string" ? chunk : chunk.toString("utf8");
+    }
+    return convertWithMetadata(html, options ?? undefined, metadataConfig ?? undefined);
+}

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@kreuzberg/html-to-markdown",
+  "version": "2.19.0-rc.1",
+  "description": "High-performance HTML to Markdown converter for TypeScript/Node.js with a Rust core.",
+  "keywords": [
+    "html",
+    "markdown",
+    "converter",
+    "rust",
+    "cli",
+    "napi",
+    "typescript"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "Na'aman Hirschfeld",
+    "email": "nhirschfeld@gmail.com"
+  },
+  "homepage": "https://github.com/kreuzberg-dev/html-to-markdown",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kreuzberg-dev/html-to-markdown"
+  },
+  "bugs": {
+    "url": "https://github.com/kreuzberg-dev/html-to-markdown/issues"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./cli": {
+      "types": "./dist/cli.d.ts",
+      "default": "./dist/cli.js"
+    }
+  },
+  "bin": {
+    "html-to-markdown": "./dist/cli.js"
+  },
+  "scripts": {
+    "build": "pnpm --filter @kreuzberg/html-to-markdown-node run build && tsc --project tsconfig.json",
+    "clean": "rm -rf dist",
+    "lint": "biome check src",
+    "lint:fix": "biome check --write src",
+    "format:fix": "biome check --write src",
+    "format:check": "biome check src",
+    "test": "pnpm --filter @kreuzberg/html-to-markdown-node run build && vitest run",
+    "test:coverage": "pnpm --filter @kreuzberg/html-to-markdown-node run build && vitest run --coverage",
+    "test:watch": "vitest"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@kreuzberg/html-to-markdown-node": "2.19.0-rc.1"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.10",
+    "@types/node": "^25.0.3",
+    "@vitest/coverage-v8": "^4.0.16",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.16"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  }
+}