@kreuzberg/html-to-markdown-wasm 2.30.0 → 3.0.1

package/dist/README.md

@@ -17,8 +17,8 @@
   <a href="https://central.sonatype.com/artifact/dev.kreuzberg/html-to-markdown">
     <img src="https://img.shields.io/maven-central/v/dev.kreuzberg/html-to-markdown?label=Java&color=007ec6" alt="Java">
   </a>
-  <a href="https://pkg.go.dev/github.com/kreuzberg-dev/html-to-markdown/packages/go/v2/htmltomarkdown">
-    <img src="https://img.shields.io/github/v/tag/kreuzberg-dev/html-to-markdown?label=Go&color=007ec6&filter=v2.28.4" alt="Go">
+  <a href="https://pkg.go.dev/github.com/kreuzberg-dev/html-to-markdown/packages/go/v3/htmltomarkdown">
+    <img src="https://img.shields.io/github/v/tag/kreuzberg-dev/html-to-markdown?label=Go&color=007ec6&filter=v3.0.0" alt="Go">
   </a>
   <a href="https://www.nuget.org/packages/KreuzbergDev.HtmlToMarkdown/">
     <img src="https://img.shields.io/nuget/v/KreuzbergDev.HtmlToMarkdown?label=C%23&color=007ec6" alt="C#">
@@ -65,6 +65,7 @@ High-performance HTML to Markdown conversion powered by Rust. Ships as native bi
 
 - **150-280 MB/s** throughput (10-80x faster than pure Python alternatives)
 - **12 language bindings** with consistent output across all runtimes
+- **Structured result** — `convert()` returns `ConversionResult` with `content`, `metadata`, `tables`, `images`, and `warnings`
 - **Metadata extraction** — title, headers, links, images, structured data (JSON-LD, Microdata, RDFa)
 - **Visitor pattern** — custom callbacks for content filtering, URL rewriting, domain-specific dialects
 - **Table extraction** — extract structured table data (cells, headers, rendered markdown) during conversion
@@ -93,6 +94,53 @@ brew install kreuzberg-dev/tap/html-to-markdown
 
 See the **[Installation Guide](https://docs.html-to-markdown.kreuzberg.dev/getting-started/installation/)** for all languages including PHP, Go, Java, C#, Elixir, R, and WASM.
 
+### Usage
+
+`convert()` is the single entry point. It returns a structured `ConversionResult`:
+
+```python
+# Python
+from html_to_markdown import convert
+
+result = convert("<h1>Hello</h1><p>World</p>")
+print(result["content"])        # # Hello\n\nWorld
+print(result["metadata"])       # title, links, headings, …
+```
+
+```typescript
+// TypeScript / Node.js
+import { convert } from "@kreuzberg/html-to-markdown-node";
+
+const result = convert("<h1>Hello</h1><p>World</p>");
+console.log(result.content);    // # Hello\n\nWorld
+console.log(result.metadata);   // title, links, headings, …
+```
+
+```rust
+// Rust
+use html_to_markdown_rs::convert;
+
+let result = convert("<h1>Hello</h1><p>World</p>", None)?;
+println!("{}", result.content.unwrap_or_default());
+```
+
+## Language Bindings
+
+| Language | Package | Install |
+|----------|---------|---------|
+| Rust | [html-to-markdown-rs](https://crates.io/crates/html-to-markdown-rs) | `cargo add html-to-markdown-rs` |
+| Python | [html-to-markdown](https://pypi.org/project/html-to-markdown/) | `pip install html-to-markdown` |
+| TypeScript / Node.js | [@kreuzberg/html-to-markdown-node](https://www.npmjs.com/package/@kreuzberg/html-to-markdown-node) | `npm install @kreuzberg/html-to-markdown-node` |
+| WebAssembly | [@kreuzberg/html-to-markdown-wasm](https://www.npmjs.com/package/@kreuzberg/html-to-markdown-wasm) | `npm install @kreuzberg/html-to-markdown-wasm` |
+| Ruby | [html-to-markdown](https://rubygems.org/gems/html-to-markdown) | `gem install html-to-markdown` |
+| PHP | [kreuzberg-dev/html-to-markdown](https://packagist.org/packages/kreuzberg-dev/html-to-markdown) | `composer require kreuzberg-dev/html-to-markdown` |
+| Go | [htmltomarkdown](https://pkg.go.dev/github.com/kreuzberg-dev/html-to-markdown/packages/go/v3/htmltomarkdown) | `go get github.com/kreuzberg-dev/html-to-markdown/packages/go/v3` |
+| Java | [dev.kreuzberg:html-to-markdown](https://central.sonatype.com/artifact/dev.kreuzberg/html-to-markdown) | Maven / Gradle |
+| C# | [KreuzbergDev.HtmlToMarkdown](https://www.nuget.org/packages/KreuzbergDev.HtmlToMarkdown/) | `dotnet add package KreuzbergDev.HtmlToMarkdown` |
+| Elixir | [html_to_markdown](https://hex.pm/packages/html_to_markdown) | `mix deps.get html_to_markdown` |
+| R | [htmltomarkdown](https://kreuzberg-dev.r-universe.dev/htmltomarkdown) | `install.packages("htmltomarkdown")` |
+| C (FFI) | [releases](https://github.com/kreuzberg-dev/html-to-markdown/releases) | Pre-built `.so` / `.dll` / `.dylib` |
+
 ## Part of the Kreuzberg Ecosystem
 
 html-to-markdown is developed by [kreuzberg.dev](https://kreuzberg.dev) and powers the HTML conversion pipeline in [Kreuzberg](https://docs.kreuzberg.dev), a document intelligence library for extracting text from PDFs, images, and office documents.

package/dist/html_to_markdown_wasm.d.ts

@@ -1,183 +1,35 @@
 /* tslint:disable */
 /* eslint-disable */
 
-export class WasmConversionOptionsHandle {
-    free(): void;
-    [Symbol.dispose](): void;
-    constructor(options?: WasmConversionOptions | null);
-}
-
-/**
- * Result of HTML extraction with inline images
- */
-export class WasmHtmlExtraction {
-    private constructor();
-    free(): void;
-    [Symbol.dispose](): void;
-    readonly inlineImages: WasmInlineImage[];
-    readonly markdown: string;
-    readonly warnings: WasmInlineImageWarning[];
-}
-
 /**
- * Inline image data
- */
-export class WasmInlineImage {
-    private constructor();
-    free(): void;
-    [Symbol.dispose](): void;
-    readonly attributes: Record<string, string>;
-    readonly data: Uint8Array;
-    readonly description: string | undefined;
-    readonly dimensions: Uint32Array | undefined;
-    readonly filename: string | undefined;
-    readonly format: string;
-    readonly source: string;
-}
-
-/**
- * Inline image configuration
- */
-export class WasmInlineImageConfig {
-    free(): void;
-    [Symbol.dispose](): void;
-    constructor(max_decoded_size_bytes?: number | null);
-    set captureSvg(value: boolean);
-    set filenamePrefix(value: string | null | undefined);
-    set inferDimensions(value: boolean);
-}
-
-/**
- * Warning about inline image processing
- */
-export class WasmInlineImageWarning {
-    private constructor();
-    free(): void;
-    [Symbol.dispose](): void;
-    readonly index: number;
-    readonly message: string;
-}
-
-export class WasmMetadataConfig {
-    free(): void;
-    [Symbol.dispose](): void;
-    /**
-     * Create a new metadata configuration with defaults
-     *
-     * All extraction types enabled by default with 1MB structured data limit
-     */
-    constructor();
-    extract_document: boolean;
-    extract_headers: boolean;
-    extract_images: boolean;
-    extract_links: boolean;
-    extract_structured_data: boolean;
-    max_structured_data_size: number;
-}
-
-/**
- * Convert HTML to Markdown
+ * Convert HTML to Markdown, returning a JavaScript object with structured content, metadata,
+ * images, and warnings in a single pass.
  *
- * # Arguments
- *
- * * `html` - The HTML string to convert
- * * `options` - Optional conversion options (as a JavaScript object)
- *
- * # Example
- *
- * ```javascript
- * import { convert } from 'html-to-markdown-wasm';
- *
- * const html = '<h1>Hello World</h1>';
- * const markdown = convert(html);
- * console.log(markdown); // # Hello World
- * ```
- */
-export function convert(html: string, options?: WasmConversionOptions | null): string;
-
-export function convertBytes(html: Uint8Array, options?: WasmConversionOptions | null): string;
-
-export function convertBytesWithInlineImages(html: Uint8Array, options?: WasmConversionOptions | null, image_config?: WasmInlineImageConfig | null): WasmHtmlExtraction;
-
-/**
- * Convert HTML bytes to Markdown with metadata extraction
- *
- * # Arguments
- *
- * * `html` - The HTML bytes to convert
- * * `options` - Optional conversion options (as a JavaScript object)
- * * `metadata_config` - Metadata extraction configuration
- *
- * # Returns
- *
- * JavaScript object with `markdown` (string) and `metadata` (object) fields
- */
-export function convertBytesWithMetadata(html: Uint8Array, options?: WasmConversionOptions | null, metadata_config?: WasmMetadataConfig | null): any;
-
-export function convertBytesWithOptionsHandle(html: Uint8Array, handle: WasmConversionOptionsHandle): string;
-
-export function convertWithInlineImages(html: string, options?: WasmConversionOptions | null, image_config?: WasmInlineImageConfig | null): WasmHtmlExtraction;
-
-/**
- * Convert HTML to Markdown with metadata extraction
- *
- * # Arguments
- *
- * * `html` - The HTML string to convert
- * * `options` - Optional conversion options (as a JavaScript object)
- * * `metadata_config` - Metadata extraction configuration
- *
- * # Returns
- *
- * JavaScript object with `markdown` (string) and `metadata` (object) fields
- *
- * # Example
- *
- * ```javascript
- * import { convertWithMetadata, WasmMetadataConfig } from 'html-to-markdown-wasm';
- *
- * const html = '<h1>Hello World</h1><a href="https://example.com">Link</a>';
- * const config = new WasmMetadataConfig();
- * config.extractHeaders = true;
- * config.extractLinks = true;
- *
- * const result = convertWithMetadata(html, null, config);
- * console.log(result.markdown); // # Hello World\n\n[Link](https://example.com)
- * console.log(result.metadata.headers); // [{ level: 1, text: "Hello World", ... }]
- * console.log(result.metadata.links); // [{ href: "https://example.com", text: "Link", ... }]
- * ```
- */
-export function convertWithMetadata(html: string, options?: WasmConversionOptions | null, metadata_config?: WasmMetadataConfig | null): any;
-
-export function convertWithOptionsHandle(html: string, handle: WasmConversionOptionsHandle): string;
-
-/**
- * Convert HTML to Markdown with structured table extraction
+ * This is the primary API entry point. Returns a JavaScript object with:
+ * - `content`: converted text (string or null)
+ * - `document`: structured document tree (object or null)
+ * - `metadata`: extracted HTML metadata (object or null)
+ * - `tables`: array of extracted table data
+ * - `warnings`: array of non-fatal processing warnings
  *
  * # Arguments
  *
  * * `html` - The HTML string to convert
  * * `options` - Optional conversion options (as a JavaScript object)
- * * `metadata_config` - Optional metadata extraction configuration
- *
- * # Returns
- *
- * JavaScript object with `content` (string), `tables` (array), and `metadata` (object|null) fields
  *
  * # Example
  *
  * ```javascript
- * import { convertWithTables } from 'html-to-markdown-wasm';
+ * import { convert } from 'html-to-markdown-wasm';
  *
- * const html = '<table><tr><th>Name</th></tr><tr><td>Alice</td></tr></table>';
- * const result = convertWithTables(html, null, null);
- * console.log(result.content);
- * console.log(result.tables[0].cells);
+ * const html = '<h1>Hello World</h1><p>Some text.</p>';
+ * const result = convert(html, null);
+ * console.log(result.content);   // '# Hello World\n\nSome text.'
+ * console.log(result.tables);    // []
+ * console.log(result.warnings);  // []
  * ```
  */
-export function convertWithTables(html: string, options?: WasmConversionOptions | null, metadata_config?: WasmMetadataConfig | null): any;
-
-export function createConversionOptionsHandle(options?: WasmConversionOptions | null): WasmConversionOptionsHandle;
+export function convert(html: string, options?: WasmConversionOptions | null): WasmConversionResult;
 
 /**
  * Initialize panic hook for better error messages in the browser
@@ -195,6 +47,7 @@ export type WasmNewlineStyle = "spaces" | "backslash";
 export type WasmCodeBlockStyle = "indented" | "backticks" | "tildes";
 export type WasmHighlightStyle = "doubleEqual" | "html" | "bold" | "none";
 export type WasmPreprocessingPreset = "minimal" | "standard" | "aggressive";
+export type WasmOutputFormat = "markdown" | "djot" | "plain";
 
 export interface WasmPreprocessingOptions {
   enabled?: boolean;
@@ -235,4 +88,78 @@ export interface WasmConversionOptions {
   debug?: boolean;
   stripTags?: string[];
   preserveTags?: string[];
+  skipImages?: boolean;
+  outputFormat?: WasmOutputFormat;
+  includeDocumentStructure?: boolean;
+  extractImages?: boolean;
+  maxImageSize?: number;
+  captureSvg?: boolean;
+  inferDimensions?: boolean;
+}
+
+/** A single cell in a structured table grid. */
+export interface WasmGridCell {
+  content: string;
+  row: number;
+  col: number;
+  rowSpan: number;
+  colSpan: number;
+  isHeader: boolean;
+}
+
+/** Structured table grid with cell-level data. */
+export interface WasmTableGrid {
+  rows: number;
+  cols: number;
+  cells: WasmGridCell[];
+}
+
+/** A table extracted during conversion. */
+export interface WasmConversionTable {
+  grid: WasmTableGrid;
+  markdown: string;
+}
+
+/** Non-fatal warning emitted during conversion. */
+export interface WasmConversionWarning {
+  /** Human-readable warning message. */
+  message: string;
+  /** Warning kind identifier. */
+  kind: string;
+}
+
+/** An extracted inline image from the HTML document. */
+export interface WasmInlineImage {
+  /** Raw image data as a Uint8Array. */
+  data: Uint8Array;
+  /** Image format (png, jpeg, gif, svg, etc.). */
+  format: string;
+  /** Generated or provided filename, or null. */
+  filename: string | null;
+  /** Alt text or description, or null. */
+  description: string | null;
+  /** Image width in pixels, or null if not available. */
+  width: number | null;
+  /** Image height in pixels, or null if not available. */
+  height: number | null;
+  /** Source type ("img_data_uri" or "svg_element"). */
+  source: string;
+  /** HTML attributes from the source element. */
+  attributes: Record<string, string>;
+}
+
+/** Result of the convert() API. */
+export interface WasmConversionResult {
+  /** Converted text output (markdown, djot, or plain text), or null. */
+  content: string | null;
+  /** Structured document tree serialized as a JSON value, or null. */
+  document: unknown | null;
+  /** Extracted HTML metadata serialized as a JSON value, or null. */
+  metadata: unknown | null;
+  /** All tables found in the HTML, in document order. */
+  tables: WasmConversionTable[];
+  /** Extracted inline images (data URIs and SVGs). */
+  images: WasmInlineImage[];
+  /** Non-fatal processing warnings. */
+  warnings: WasmConversionWarning[];
 }