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

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright 2024-2025 Na'aman Hirschfeld
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,40 +1,103 @@
-# 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.
+# html-to-markdown
+
+<div align="center" style="display: flex; flex-wrap: wrap; gap: 8px; justify-content: center; margin: 20px 0;">
+  <!-- Language Bindings -->
+  <a href="https://crates.io/crates/html-to-markdown-rs">
+    <img src="https://img.shields.io/crates/v/html-to-markdown-rs?label=Rust&color=007ec6" alt="Rust">
+  </a>
+  <a href="https://pypi.org/project/html-to-markdown/">
+    <img src="https://img.shields.io/pypi/v/html-to-markdown?label=Python&color=007ec6" alt="Python">
+  </a>
+  <a href="https://www.npmjs.com/package/@kreuzberg/html-to-markdown-node">
+    <img src="https://img.shields.io/npm/v/@kreuzberg/html-to-markdown-node?label=Node.js&color=007ec6" alt="Node.js">
+  </a>
+  <a href="https://www.npmjs.com/package/@kreuzberg/html-to-markdown-wasm">
+    <img src="https://img.shields.io/npm/v/@kreuzberg/html-to-markdown-wasm?label=WASM&color=007ec6" alt="WASM">
+  </a>
+  <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/badge/Go-v2.19.0-007ec6" 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#">
+  </a>
+  <a href="https://packagist.org/packages/goldziher/html-to-markdown">
+    <img src="https://img.shields.io/packagist/v/goldziher/html-to-markdown?label=PHP&color=007ec6" alt="PHP">
+  </a>
+  <a href="https://rubygems.org/gems/html-to-markdown">
+    <img src="https://img.shields.io/gem/v/html-to-markdown?label=Ruby&color=007ec6" alt="Ruby">
+  </a>
+  <a href="https://hex.pm/packages/html_to_markdown">
+    <img src="https://img.shields.io/hexpm/v/html_to_markdown?label=Elixir&color=007ec6" alt="Elixir">
+  </a>
+
+  <!-- Project Info -->
+  <a href="https://github.com/kreuzberg-dev/html-to-markdown/blob/main/LICENSE">
+    <img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License">
+  </a>
+</div>
+
+<img width="1128" height="191" alt="html-to-markdown" src="https://github.com/user-attachments/assets/419fc06c-8313-4324-b159-4b4d3cfce5c0" />
+
+<div align="center" style="margin-top: 20px;">
+  <a href="https://discord.gg/pXxagNK2zN">
+      <img height="22" src="https://img.shields.io/badge/Discord-Join%20our%20community-7289da?logo=discord&logoColor=white" alt="Discord">
+  </a>
+</div>
+
+
+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
+```
+
+
+
+Requires Node.js 18+ or Bun. Native bindings provide superior performance.
+
+**npm:**
+```bash
+npm install @kreuzberg/html-to-markdown
+```
+
+**pnpm:**
+```bash
 pnpm add @kreuzberg/html-to-markdown
+```
+
+**yarn:**
+```bash
 yarn add @kreuzberg/html-to-markdown
+```
+
+**bun:**
+```bash
 bun add @kreuzberg/html-to-markdown
+```
+
+Alternatively, use the WebAssembly version for browser/edge environments:
 
-# WebAssembly (browser/edge/Node without native toolchain)
+```bash
 npm install @kreuzberg/html-to-markdown-wasm
 ```
 
-## Migration Guide (v2.18.x → v2.19.0)
 
-### Breaking Change: Scoped npm Packages
+
+
+# Migration Guide: TypeScript 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
+### Package Installation Update
 
 **Before (v2.18.x):**
 ```bash
@@ -48,30 +111,30 @@ npm install @kreuzberg/html-to-markdown-node
 npm install @kreuzberg/html-to-markdown-wasm
 ```
 
-#### Import Statement Update
+### Import Statement Update
 
 **Before:**
 ```typescript
-import { convert } from 'html-to-markdown-node';
-import { convert } from 'html-to-markdown-wasm';
+import { convert } from &#39;html-to-markdown-node&#39;;
+import { convert } from &#39;html-to-markdown-wasm&#39;;
 ```
 
 **After:**
 ```typescript
-import { convert } from '@kreuzberg/html-to-markdown-node';
-import { convert } from '@kreuzberg/html-to-markdown-wasm';
+import { convert } from &#39;@kreuzberg/html-to-markdown-node&#39;;
+import { convert } from &#39;@kreuzberg/html-to-markdown-wasm&#39;;
 ```
 
-#### TypeScript Declaration Update
+### 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"]
+  &#34;compilerOptions&#34;: {
+    &#34;paths&#34;: {
+      &#34;html-to-markdown&#34;: [&#34;node_modules/html-to-markdown-node&#34;]
     }
   }
 }
@@ -80,27 +143,27 @@ Update your TypeScript configuration if you have imports from the old package na
 **After:**
 ```json
 {
-  "compilerOptions": {
-    "paths": {
-      "@kreuzberg/html-to-markdown": ["node_modules/@kreuzberg/html-to-markdown-node"]
+  &#34;compilerOptions&#34;: {
+    &#34;paths&#34;: {
+      &#34;@kreuzberg/html-to-markdown&#34;: [&#34;node_modules/@kreuzberg/html-to-markdown-node&#34;]
     }
   }
 }
 ```
 
-#### Deno Update
+### Deno Update
 
 **Before:**
 ```typescript
-import { convert } from "npm:html-to-markdown-wasm";
+import { convert } from &#34;npm:html-to-markdown-wasm&#34;;
 ```
 
 **After:**
 ```typescript
-import { convert } from "npm:@kreuzberg/html-to-markdown-wasm";
+import { convert } from &#34;npm:@kreuzberg/html-to-markdown-wasm&#34;;
 ```
 
-#### Summary of Changes
+## Summary of Changes
 
 - All npm packages now use `@kreuzberg` scope
 - `html-to-markdown-node` → `@kreuzberg/html-to-markdown-node`
@@ -108,243 +171,276 @@ import { convert } from "npm:@kreuzberg/html-to-markdown-wasm";
 - TypeScript types and APIs are identical
 - No functional changes to the library
 
+
+
+
+## Performance Snapshot
+
+Apple M4 • Real Wikipedia documents • `convert()` (TypeScript (Node.js))
+
+| Document | Size | Latency | Throughput |
+| -------- | ---- | ------- | ---------- |
+| Lists (Timeline) | 129KB | 0.58ms | 222 MB/s |
+| Tables (Countries) | 360KB | 1.89ms | 190 MB/s |
+| Mixed (Python wiki) | 656KB | 4.21ms | 156 MB/s |
+
+
+See [Performance Guide](../../examples/performance/) for detailed benchmarks.
+
+
 ## Quick Start
 
-**Basic conversion with type safety:**
+Basic conversion:
+
 ```typescript
-import { convert } from '@kreuzberg/html-to-markdown';
+import { convert } from &#39;@kreuzberg/html-to-markdown&#39;;
 
-const markdown: string = convert('<h1>Hello World</h1>');
+const markdown: string = convert(&#39;&lt;h1&gt;Hello World&lt;/h1&gt;&#39;);
 console.log(markdown); // # Hello World
 ```
 
-**With conversion options:**
+
+
+With conversion options:
+
 ```typescript
-import { convert, ConversionOptions } from '@kreuzberg/html-to-markdown';
+import { convert, ConversionOptions } from &#39;@kreuzberg/html-to-markdown&#39;;
 
 const options: ConversionOptions = {
-  headingStyle: 'atx',
+  headingStyle: &#39;atx&#39;,
   listIndentWidth: 2,
   wrap: true,
 };
 
-const markdown = convert('<h1>Title</h1><p>Content</p>', options);
+const markdown = convert(&#39;&lt;h1&gt;Title&lt;/h1&gt;&lt;p&gt;Content&lt;/p&gt;&#39;, 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).
+**`convert(html: string, options?: ConversionOptions): string`**
 
-#### `convertFile(filePath: string, options?: ConversionOptions): Promise<string>`
-Asynchronously convert an HTML file to Markdown.
+Basic HTML-to-Markdown conversion. Fast and simple.
 
-#### `convertStream(stream: NodeJS.ReadableStream, options?: ConversionOptions): Promise<string>`
-Convert HTML from a readable stream (stdin, file stream, network).
+**`convertWithMetadata(html: string, options?: ConversionOptions, config?: MetadataConfig): { markdown: string; metadata: Metadata }`**
 
-### Metadata Extraction Functions
+Extract Markdown plus metadata (headers, links, images, structured data) in a single pass. See [Metadata Extraction Guide](../../examples/metadata-extraction/).
 
-Requires `metadata` feature flag.
+**`convertWithVisitor(html: string, options: { visitor: Visitor } & ConversionOptions): string`**
 
-#### `convertWithMetadata(html: string, options?, metadataConfig?): { markdown: string; metadata: JsExtendedMetadata }`
-Convert and extract document metadata, headers, links, images, and structured data.
+Customize conversion with visitor callbacks for element interception. See [Visitor Pattern Guide](../../examples/visitor-pattern/).
 
-#### `convertWithMetadataBuffer(buffer: Buffer | Uint8Array, options?, metadataConfig?): JsMetadataExtraction`
-Convert from Buffer with metadata extraction.
+**`convertWithAsyncVisitor(html: string, options: { visitor: AsyncVisitor } & ConversionOptions): Promise<string>`**
 
-#### `convertFileWithMetadata(filePath: string, options?, metadataConfig?): Promise<JsMetadataExtraction>`
-Convert HTML file with metadata extraction.
+Async version of visitor pattern for I/O operations.
 
-#### `convertStreamWithMetadata(stream: NodeJS.ReadableStream, options?, metadataConfig?): Promise<JsMetadataExtraction>`
-Convert stream with metadata extraction.
+**`convertWithInlineImages(html: string, config?: InlineImageConfig): { markdown: string; images: ImageData[]; warnings: string[] }`**
 
-#### `hasMetadataSupport(): boolean`
-Check if metadata extraction is available at runtime.
+Extract base64-encoded inline images with metadata.
 
-### 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.
+### Options
 
-#### `convertWithAsyncVisitor(html: string, config: { visitor: AsyncVisitor; options?: ConversionOptions }): Promise<string>`
-Convert with async visitor methods for I/O operations.
+**`ConversionOptions`** – Key configuration fields:
+- `heading_style`: Heading format (`"underlined"` | `"atx"` | `"atx_closed"`) — default: `"underlined"`
+- `list_indent_width`: Spaces per indent level — default: `2`
+- `bullets`: Bullet characters cycle — default: `"*+-"`
+- `wrap`: Enable text wrapping — default: `false`
+- `wrap_width`: Wrap at column — default: `80`
+- `code_language`: Default fenced code block language — default: none
+- `extract_metadata`: Embed metadata as YAML frontmatter — default: `false`
+- `output_format`: Output markup format (`"markdown"` | `"djot"`) — default: `"markdown"`
 
-## Type Definitions
+**`MetadataConfig`** – Selective metadata extraction:
+- `extract_headers`: h1-h6 elements — default: `true`
+- `extract_links`: Hyperlinks — default: `true`
+- `extract_images`: Image elements — default: `true`
+- `extract_structured_data`: JSON-LD, Microdata, RDFa — default: `true`
+- `max_structured_data_size`: Size limit in bytes — default: `100KB`
 
-### 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 _
-}
+
+## Djot Output Format
+
+The 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.
+
+### Syntax Differences
+
+| Element | Markdown | Djot |
+|---------|----------|------|
+| Strong | `**text**` | `*text*` |
+| Emphasis | `*text*` | `_text_` |
+| Strikethrough | `~~text~~` | `{-text-}` |
+| Inserted/Added | N/A | `{+text+}` |
+| Highlighted | N/A | `{=text=}` |
+| Subscript | N/A | `~text~` |
+| Superscript | N/A | `^text^` |
+
+### Example Usage
+
+```python
+from html_to_markdown import convert, ConversionOptions
+
+html = "<p>This is <strong>bold</strong> and <em>italic</em> text.</p>"
+
+# Default Markdown output
+markdown = convert(html)
+# Result: "This is **bold** and *italic* text."
+
+# Djot output
+djot = convert(html, ConversionOptions(output_format="djot"))
+# Result: "This is *bold* and _italic_ text."
 ```
 
-### Metadata Types
+Djot'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.
+
+
+
+## Metadata Extraction
+
+The metadata extraction feature enables comprehensive document analysis during conversion. Extract document properties, headers, links, images, and structured data in a single pass.
+
+**Use Cases:**
+- **SEO analysis** – Extract title, description, Open Graph tags, Twitter cards
+- **Table of contents generation** – Build structured outlines from heading hierarchy
+- **Content migration** – Document all external links and resources
+- **Accessibility audits** – Check for images without alt text, empty links, invalid heading hierarchy
+- **Link validation** – Classify and validate anchor, internal, external, email, and phone links
+
+**Zero Overhead When Disabled:** Metadata extraction adds negligible overhead and happens during the HTML parsing pass. Disable unused metadata types in `MetadataConfig` to optimize further.
+
+### Example: Quick Start
+
+
 ```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)
-}
+import { convertWithMetadata } from 'html-to-markdown';
 
-interface JsExtendedMetadata {
-  document: JsDocumentMetadata;
-  headers: JsHeaderMetadata[];
-  links: JsLinkMetadata[];
-  images: JsImageMetadata[];
-  structuredData: JsStructuredData[];
-}
+const html = '<h1>Article</h1><img src="test.jpg" alt="test">';
+const { markdown, metadata } = convertWithMetadata(html);
 
-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>;
-}
+console.log(metadata.document.title);      // Document title
+console.log(metadata.headers);             // All h1-h6 elements
+console.log(metadata.links);               // All hyperlinks
+console.log(metadata.images);              // All images with alt text
+console.log(metadata.structuredData);      // JSON-LD, Microdata, RDFa
 ```
 
-### Visitor Types
+
+
+For detailed examples including SEO extraction, table-of-contents generation, link validation, and accessibility audits, see the [Metadata Extraction Guide](../../examples/metadata-extraction/).
+
+
+
+
+## Visitor Pattern
+
+The visitor pattern enables custom HTML→Markdown conversion logic by providing callbacks for specific HTML elements during traversal. Use visitors to transform content, filter elements, validate structure, or collect analytics.
+
+**Use Cases:**
+- **Custom Markdown dialects** – Convert to Obsidian, Notion, or other flavors
+- **Content filtering** – Remove tracking pixels, ads, or unwanted elements
+- **URL rewriting** – Rewrite CDN URLs, add query parameters, validate links
+- **Accessibility validation** – Check alt text, heading hierarchy, link text
+- **Analytics** – Track element usage, link destinations, image sources
+
+**Supported Visitor Methods:** 40+ callbacks for text, inline elements, links, images, headings, lists, blocks, and tables.
+
+### Example: Quick Start
+
+
 ```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
-}
+import { convertWithVisitor, type Visitor, type NodeContext, type VisitResult } from 'html-to-markdown';
 
-interface NodeContext {
-  nodeType: string;
-  tagName: string;
-  attributes: Record<string, string>;
-  depth: number;
-  indexInParent: number;
-  parentTag: string | null;
-  isInline: boolean;
-}
+const visitor: Visitor = {
+  visitLink(ctx: NodeContext, href: string, text: string, title?: string): VisitResult {
+    // Rewrite CDN URLs
+    if (href.startsWith('https://old-cdn.com')) {
+      href = href.replace('https://old-cdn.com', 'https://new-cdn.com');
+    }
+    return { type: 'custom', output: `[${text}](${href})` };
+  },
 
-type VisitResult =
-  | { type: 'continue' }
-  | { type: 'custom'; output: string }
-  | { type: 'skip' }
-  | { type: 'preserveHtml' }
-  | { type: 'error'; message: string };
-```
+  visitImage(ctx: NodeContext, src: string, alt?: string, title?: string): VisitResult {
+    // Skip tracking pixels
+    if (src.includes('tracking')) {
+      return { type: 'skip' };
+    }
+    return { type: 'continue' };
+  },
+};
 
-## Error Handling
+const html = '<a href="https://old-cdn.com/file.pdf">Download</a>';
+const markdown = convertWithVisitor(html, { visitor });
+```
 
+Async support:
 ```typescript
-try {
-  const markdown = convert(html);
-} catch (error) {
-  if (error instanceof Error) {
-    console.error('Conversion failed:', error.message);
-  }
-}
+import { convertWithAsyncVisitor, type AsyncVisitor } from 'html-to-markdown';
+
+const asyncVisitor: AsyncVisitor = {
+  async visitLink(ctx, href, text, title) {
+    const isValid = await validateUrl(href);
+    return isValid ? { type: 'continue' } : { type: 'error', message: `Broken link: ${href}` };
+  },
+};
+
+const markdown = await convertWithAsyncVisitor(html, { visitor: asyncVisitor });
 ```
 
-Inputs with binary data (PDF bytes coerced to strings) raise errors with message: `Invalid input`.
 
-## Examples
 
-See comprehensive guides in the examples directory:
+For comprehensive examples including content filtering, link footnotes, accessibility validation, and asynchronous URL validation, see the [Visitor Pattern Guide](../../examples/visitor-pattern/).
+
 
-- **[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
+## Examples
 
-For strict type checking:
+- [Visitor Pattern Guide](../../examples/visitor-pattern/)
+- [Metadata Extraction Guide](../../examples/metadata-extraction/)
+- [Performance Guide](../../examples/performance/)
 
-```json
-{
-  "compilerOptions": {
-    "strict": true,
-    "noUncheckedIndexedAccess": true,
-    "exactOptionalPropertyTypes": true,
-    "noImplicitAny": true,
-    "noImplicitThis": true,
-    "strictNullChecks": true,
-    "strictFunctionTypes": true,
-    "strictPropertyInitialization": true,
-    "noImplicitReturns": true
-  }
-}
-```
+## Links
 
-All bindings are fully typed with no `any` types. Leverage TypeScript for compile-time safety.
+- **GitHub:** [github.com/kreuzberg-dev/html-to-markdown](https://github.com/kreuzberg-dev/html-to-markdown)
 
-## Performance
+- **npm:** [npmjs.com/@kreuzberg/html-to-markdown-node](https://www.npmjs.com/package/@kreuzberg/html-to-markdown-node)
+- **WASM:** [npmjs.com/@kreuzberg/html-to-markdown-wasm](https://www.npmjs.com/package/@kreuzberg/html-to-markdown-wasm)
 
-Benchmarks from Apple M4 (ops/sec):
+- **Kreuzberg Ecosystem:** [kreuzberg.dev](https://kreuzberg.dev)
+- **Discord:** [discord.gg/pXxagNK2zN](https://discord.gg/pXxagNK2zN)
 
-| 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     |
+## Contributing
 
-Run `task bench:harness -- --frameworks node` to benchmark locally.
+We welcome contributions! Please see our [Contributing Guide](https://github.com/kreuzberg-dev/html-to-markdown/blob/main/CONTRIBUTING.md) for details on:
 
-## Links
+- Setting up the development environment
+- Running tests locally
+- Submitting pull requests
+- Reporting issues
+
+All contributions must follow our code quality standards (enforced via pre-commit hooks):
 
-- [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)
+- Proper test coverage (Rust 95%+, language bindings 80%+)
+- Formatting and linting checks
+- Documentation for public APIs
 
 ## License
 
-MIT
+MIT License – see [LICENSE](https://github.com/kreuzberg-dev/html-to-markdown/blob/main/LICENSE).
+
+## Support
+
+If you find this library useful, consider [sponsoring the project](https://github.com/sponsors/kreuzberg-dev).
+
+Have questions or run into issues? We're here to help:
+
+- **GitHub Issues:** [github.com/kreuzberg-dev/html-to-markdown/issues](https://github.com/kreuzberg-dev/html-to-markdown/issues)
+- **Discussions:** [github.com/kreuzberg-dev/html-to-markdown/discussions](https://github.com/kreuzberg-dev/html-to-markdown/discussions)
+- **Discord Community:** [discord.gg/pXxagNK2zN](https://discord.gg/pXxagNK2zN)

package/dist/index.d.ts

@@ -30,7 +30,7 @@ export declare function convertStreamWithInlineImages(stream: Readable | AsyncIt
  * links, images, and structured data (JSON-LD, Microdata, RDFa).
  *
  * @param html HTML content to convert
- * @param options Optional conversion configuration
+ * @param options Optional conversion configuration. Supports `skipImages` to skip image conversion
  * @param metadataConfig Optional metadata extraction configuration
  * @returns Object with converted markdown and extracted metadata
  *
@@ -51,7 +51,7 @@ export declare function convertStreamWithInlineImages(stream: Readable | AsyncIt
  *   </html>
  * `;
  *
- * const { markdown, metadata } = await convertWithMetadata(html, undefined, {
+ * const { markdown, metadata } = convertWithMetadata(html, undefined, {
  *   extractHeaders: true,
  *   extractLinks: true,
  *   extractImages: true,
@@ -78,3 +78,69 @@ export declare function convertFileWithMetadata(filePath: string, options?: JsCo
  * 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>;
+/**
+ * Type for visitor callback that receives parsed context object
+ */
+type VisitorCallback<TContext = unknown, TResult = {
+    type: string;
+    output?: string;
+}> = (context: TContext) => Promise<TResult>;
+/**
+ * Type for wrapped visitor callback that handles JSON strings
+ */
+type WrappedVisitorCallback = (jsonString: string) => Promise<string>;
+/**
+ * Wraps a single visitor callback to handle JSON serialization/deserialization automatically.
+ *
+ * The native NAPI bindings expect visitor callbacks with signature:
+ *   `(jsonString: string) => Promise<string>`
+ *
+ * This wrapper allows you to write callbacks that receive parsed objects:
+ *   `(context: NodeContext) => Promise<{type: string}>`
+ *
+ * @param callback - Visitor callback that receives parsed context object
+ * @returns Wrapped callback that handles JSON string conversion
+ *
+ * @example
+ * ```ts
+ * const wrappedCallback = wrapVisitorCallback(async (ctx) => {
+ *   console.log('Tag name:', ctx.tagName);
+ *   return { type: 'continue' };
+ * });
+ * ```
+ */
+export declare function wrapVisitorCallback<TContext, TResult>(callback: VisitorCallback<TContext, TResult>): WrappedVisitorCallback;
+/**
+ * Type for visitor object with callbacks that receive parsed objects
+ */
+type VisitorObject = Record<string, VisitorCallback>;
+/**
+ * Type for wrapped visitor object with JSON-handling callbacks
+ */
+type WrappedVisitorObject = Record<string, WrappedVisitorCallback>;
+/**
+ * Wraps all callbacks in a visitor object to handle JSON serialization/deserialization.
+ *
+ * This is a convenience function to wrap all callbacks in a visitor object at once.
+ *
+ * @param visitor - Visitor object with callbacks that receive parsed objects
+ * @returns Wrapped visitor object with JSON-handling callbacks
+ *
+ * @example
+ * ```ts
+ * const visitor = {
+ *   visitElementStart: async (ctx: NodeContext) => {
+ *     console.log('Tag:', ctx.tagName);
+ *     return { type: 'continue' };
+ *   },
+ *   visitText: async (ctx: NodeContext, text: string) => {
+ *     console.log('Text:', text);
+ *     return { type: 'continue' };
+ *   },
+ * };
+ *
+ * const wrapped = wrapVisitorCallbacks(visitor);
+ * const result = await convertWithVisitor(html, undefined, wrapped);
+ * ```
+ */
+export declare function wrapVisitorCallbacks(visitor: VisitorObject): WrappedVisitorObject;

package/dist/index.js

@@ -62,7 +62,7 @@ export async function convertStreamWithInlineImages(stream, options, imageConfig
  * links, images, and structured data (JSON-LD, Microdata, RDFa).
  *
  * @param html HTML content to convert
- * @param options Optional conversion configuration
+ * @param options Optional conversion configuration. Supports `skipImages` to skip image conversion
  * @param metadataConfig Optional metadata extraction configuration
  * @returns Object with converted markdown and extracted metadata
  *
@@ -83,7 +83,7 @@ export async function convertStreamWithInlineImages(stream, options, imageConfig
  *   </html>
  * `;
  *
- * const { markdown, metadata } = await convertWithMetadata(html, undefined, {
+ * const { markdown, metadata } = convertWithMetadata(html, undefined, {
  *   extractHeaders: true,
  *   extractLinks: true,
  *   extractImages: true,
@@ -124,3 +124,64 @@ export async function convertStreamWithMetadata(stream, options, metadataConfig)
     }
     return convertWithMetadata(html, options ?? undefined, metadataConfig ?? undefined);
 }
+/**
+ * Wraps a single visitor callback to handle JSON serialization/deserialization automatically.
+ *
+ * The native NAPI bindings expect visitor callbacks with signature:
+ *   `(jsonString: string) => Promise<string>`
+ *
+ * This wrapper allows you to write callbacks that receive parsed objects:
+ *   `(context: NodeContext) => Promise<{type: string}>`
+ *
+ * @param callback - Visitor callback that receives parsed context object
+ * @returns Wrapped callback that handles JSON string conversion
+ *
+ * @example
+ * ```ts
+ * const wrappedCallback = wrapVisitorCallback(async (ctx) => {
+ *   console.log('Tag name:', ctx.tagName);
+ *   return { type: 'continue' };
+ * });
+ * ```
+ */
+export function wrapVisitorCallback(callback) {
+    return async (jsonString) => {
+        const context = JSON.parse(jsonString);
+        const result = await callback(context);
+        return JSON.stringify(result);
+    };
+}
+/**
+ * Wraps all callbacks in a visitor object to handle JSON serialization/deserialization.
+ *
+ * This is a convenience function to wrap all callbacks in a visitor object at once.
+ *
+ * @param visitor - Visitor object with callbacks that receive parsed objects
+ * @returns Wrapped visitor object with JSON-handling callbacks
+ *
+ * @example
+ * ```ts
+ * const visitor = {
+ *   visitElementStart: async (ctx: NodeContext) => {
+ *     console.log('Tag:', ctx.tagName);
+ *     return { type: 'continue' };
+ *   },
+ *   visitText: async (ctx: NodeContext, text: string) => {
+ *     console.log('Text:', text);
+ *     return { type: 'continue' };
+ *   },
+ * };
+ *
+ * const wrapped = wrapVisitorCallbacks(visitor);
+ * const result = await convertWithVisitor(html, undefined, wrapped);
+ * ```
+ */
+export function wrapVisitorCallbacks(visitor) {
+    const wrapped = {};
+    for (const [methodName, callback] of Object.entries(visitor)) {
+        if (typeof callback === "function") {
+            wrapped[methodName] = wrapVisitorCallback(callback);
+        }
+    }
+    return wrapped;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kreuzberg/html-to-markdown",
-  "version": "2.19.0-rc.1",
+  "version": "2.23.4",
   "description": "High-performance HTML to Markdown converter for TypeScript/Node.js with a Rust core.",
   "keywords": [
     "html",
@@ -39,30 +39,19 @@
   "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"
+    "@kreuzberg/html-to-markdown-node": "2.23.4"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.3.10",
-    "@types/node": "^25.0.3",
-    "@vitest/coverage-v8": "^4.0.16",
+    "@biomejs/biome": "^2.3.11",
+    "@types/node": "^25.0.9",
+    "@vitest/coverage-v8": "^4.0.17",
     "typescript": "^5.9.3",
-    "vitest": "^4.0.16"
+    "vitest": "^4.0.17"
   },
   "engines": {
     "node": ">=18"
@@ -70,5 +59,16 @@
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
+  },
+  "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"
   }
-}
+}