html-to-markdown 2.18.0 → 2.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 46277b2cbcf02b063ea61a2fe083829ac80bd395e10c5799f7ace0e82cfdf4ed
-  data.tar.gz: fbbd6a3ef8f45cc35d85ac7a51b77361c198ab13c981ebb0dc5ad703df8de54c
+  metadata.gz: 846bb8410c19e5a5ee99a7998d78f6f9aa21e698dc2cf1ac4ab6aaf45e257cca
+  data.tar.gz: 04cc1deab74259fc77481f30e1fdf236439b86b2fd05b1a5efc06d873e54f806
 SHA512:
-  metadata.gz: 57db78a9ffbd68b713a4265a0d7cc68d67fbab07ac8a9963b5b7e1c213ce9ec0aec8ef4cbc5cb76aa67bc0cd4b8f976efd45f0e55c458f85136174f25344e74b
-  data.tar.gz: 70dcae164812ac269efb2b0a36224b4320b0f1f6341970ee5d626666189d6ede0aac3921edb72f36f30896e257eefdbd55b09328613f02abde501721bd31e944
+  metadata.gz: 4d1adafa16b6633374c5f509881bb8feb5ec670bfd5c7388c9100c6d3d6a53538db86de6cfbce81a0976af7ad8865fbd5242b639631828d67a88cefc938763ae
+  data.tar.gz: f292a71719770821f0e5000d263627f8f44facc74f4c0f6f7da0e4c7feb66034e57baf254163ac88a58f6ebf911a8787797e2742bd31bba9a27fe289799c833d

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    html-to-markdown (2.18.0)
+    html-to-markdown (2.19.0)
       rb_sys (>= 0.9, < 1.0)
 
 GEM
@@ -29,16 +29,8 @@ GEM
     diff-lcs (1.6.2)
     drb (2.2.3)
     ffi (1.17.2)
-    ffi (1.17.2-aarch64-linux-gnu)
-    ffi (1.17.2-aarch64-linux-musl)
-    ffi (1.17.2-arm-linux-gnu)
-    ffi (1.17.2-arm-linux-musl)
     ffi (1.17.2-arm64-darwin)
-    ffi (1.17.2-x86-linux-gnu)
-    ffi (1.17.2-x86-linux-musl)
-    ffi (1.17.2-x86_64-darwin)
     ffi (1.17.2-x86_64-linux-gnu)
-    ffi (1.17.2-x86_64-linux-musl)
     fileutils (1.8.0)
     i18n (1.14.8)
       concurrent-ruby (~> 1.0)
@@ -131,17 +123,8 @@ GEM
     uri (1.1.1)
 
 PLATFORMS
-  aarch64-linux-gnu
-  aarch64-linux-musl
-  arm-linux-gnu
-  arm-linux-musl
   arm64-darwin
-  ruby
-  x86-linux-gnu
-  x86-linux-musl
-  x86_64-darwin
-  x86_64-linux-gnu
-  x86_64-linux-musl
+  x86_64-linux
 
 DEPENDENCIES
   html-to-markdown!
@@ -164,18 +147,10 @@ CHECKSUMS
   diff-lcs (1.6.2) sha256=9ae0d2cba7d4df3075fe8cd8602a8604993efc0dfa934cff568969efb1909962
   drb (2.2.3) sha256=0b00d6fdb50995fe4a45dea13663493c841112e4068656854646f418fda13373
   ffi (1.17.2) sha256=297235842e5947cc3036ebe64077584bff583cd7a4e94e9a02fdec399ef46da6
-  ffi (1.17.2-aarch64-linux-gnu) sha256=c910bd3cae70b76690418cce4572b7f6c208d271f323d692a067d59116211a1a
-  ffi (1.17.2-aarch64-linux-musl) sha256=69e6556b091d45df83e6c3b19d3c54177c206910965155a6ec98de5e893c7b7c
-  ffi (1.17.2-arm-linux-gnu) sha256=d4a438f2b40224ae42ec72f293b3ebe0ba2159f7d1bd47f8417e6af2f68dbaa5
-  ffi (1.17.2-arm-linux-musl) sha256=977dfb7f3a6381206dbda9bc441d9e1f9366bf189a634559c3b7c182c497aaa3
   ffi (1.17.2-arm64-darwin) sha256=54dd9789be1d30157782b8de42d8f887a3c3c345293b57ffb6b45b4d1165f813
-  ffi (1.17.2-x86-linux-gnu) sha256=95d8f9ebea23c39888e2ab85a02c98f54acb2f4e79b829250d7267ce741dc7b0
-  ffi (1.17.2-x86-linux-musl) sha256=41741449bab2b9530f42a47baa5c26263925306fad0ac2d60887f51af2e3b24c
-  ffi (1.17.2-x86_64-darwin) sha256=981f2d4e32ea03712beb26e55e972797c2c5a7b0257955d8667ba58f2da6440e
   ffi (1.17.2-x86_64-linux-gnu) sha256=05d2026fc9dbb7cfd21a5934559f16293815b7ce0314846fee2ac8efbdb823ea
-  ffi (1.17.2-x86_64-linux-musl) sha256=97c0eb3981414309285a64dc4d466bd149e981c279a56371ef811395d68cb95c
   fileutils (1.8.0) sha256=8c6b1df54e2540bdb2f39258f08af78853aa70bad52b4d394bbc6424593c6e02
-  html-to-markdown (2.18.0)
+  html-to-markdown (2.19.0)
   i18n (1.14.8) sha256=285778639134865c5e0f6269e0b818256017e8cde89993fdfcbfb64d088824a5
   json (2.18.0) sha256=b10506aee4183f5cf49e0efc48073d7b75843ce3782c68dbeb763351c08fd505
   language_server-protocol (3.17.0.5) sha256=fd1e39a51a28bf3eec959379985a72e296e9f9acfce46f6a79d31ca8760803cc

data/README.md

@@ -1,274 +1,276 @@
-# html-to-markdown-rb
-
-Blazing-fast HTML → Markdown conversion for Ruby, powered by the same Rust engine used by our Python, Node.js, WebAssembly, and PHP packages. Ship identical Markdown across every runtime while enjoying native extension performance.
-
-[![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/html-to-markdown-node.svg?logo=npm)](https://www.npmjs.com/package/html-to-markdown-node)
-[![npm (wasm)](https://img.shields.io/npm/v/html-to-markdown-wasm.svg?logo=npm)](https://www.npmjs.com/package/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)
-
-## Features
-
-- ⚡ **Rust-fast**: Ruby bindings around a highly optimised Rust core (60‑80× faster than BeautifulSoup-based converters).
-- 🔁 **Identical output**: Shares logic with the Python wheels, npm bindings, PHP extension, WASM package, and CLI — consistent Markdown everywhere.
-- ⚙️ **Rich configuration**: Control heading styles, list indentation, whitespace handling, HTML preprocessing, and more.
-- 🖼️ **Inline image extraction**: Pull out embedded images (PNG/JPEG/SVG/data URIs) alongside Markdown.
-- 🧰 **Bundled CLI proxy**: Call the Rust CLI straight from Ruby or shell scripts.
-- 🛠️ **First-class Rails support**: Works with `Gem.win_platform?` builds, supports Trusted Publishing, and compiles on install if no native gem matches.
-
-## Documentation & Support
-
-- [GitHub repository](https://github.com/kreuzberg-dev/html-to-markdown)
-- [Issue tracker](https://github.com/kreuzberg-dev/html-to-markdown/issues)
-- [Changelog](https://github.com/kreuzberg-dev/html-to-markdown/blob/main/CHANGELOG.md)
-- [Live demo (WASM)](https://kreuzberg-dev.github.io/html-to-markdown/)
+# 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>
+
+
+Blazing-fast HTML to Markdown conversion for Ruby, powered by the same Rust engine used by our Python, Node.js, WebAssembly, and PHP packages.
+Ship identical Markdown across every runtime while enjoying native extension performance with Magnus bindings.
+
 
 ## Installation
 
 ```bash
-bundle add html-to-markdown
-# or
 gem install html-to-markdown
 ```
 
-Add the gem to your project and Bundler will compile the native Rust extension on first install.
 
-### Requirements
 
-- Ruby **3.2+** (Magnus relies on the fiber scheduler APIs added in 3.2)
-- Rust toolchain **1.85+** with Cargo available on your `$PATH`
-- Ruby development headers (`ruby-dev`, `ruby-devel`, or the platform equivalent)
+Requires Ruby 3.2+ with Magnus native extension bindings. Published for Linux, macOS.
 
-**Windows**: install [RubyInstaller with MSYS2](https://rubyinstaller.org/) (UCRT64). Run once:
 
-```powershell
-ridk exec pacman -S --needed --noconfirm base-devel mingw-w64-ucrt-x86_64-toolchain
-```
 
-This provides the standard headers (including `strings.h`) required for the bindgen step.
+
+
+
+## Performance Snapshot
+
+Apple M4 • Real Wikipedia documents • `convert()` (Ruby)
+
+| Document | Size | Latency | Throughput |
+| -------- | ---- | ------- | ---------- |
+| Lists (Timeline) | 129KB | 0.71ms | 182 MB/s |
+| Tables (Countries) | 360KB | 2.15ms | 167 MB/s |
+| Mixed (Python wiki) | 656KB | 4.89ms | 134 MB/s |
+
+
+See [Performance Guide](../../examples/performance/) for detailed benchmarks.
+
 
 ## Quick Start
 
+Basic conversion:
+
 ```ruby
 require 'html_to_markdown'
 
-html = <<~HTML
-  <h1>Welcome</h1>
-  <p>This is <strong>Rust-fast</strong> conversion!</p>
-  <ul>
-    <li>Native extension</li>
-    <li>Identical output across languages</li>
-  </ul>
-HTML
-
+html = "<h1>Hello</h1><p>This is <strong>fast</strong>!</p>"
 markdown = HtmlToMarkdown.convert(html)
-puts markdown
-# # Welcome
-#
-# This is **Rust-fast** conversion!
-#
-# - Native extension
-# - Identical output across languages
 ```
 
-## API Reference
 
-### Basic Conversion
+
+With conversion options:
 
 ```ruby
-# Simple conversion
-markdown = HtmlToMarkdown.convert(html)
+require 'html_to_markdown'
 
-# With options (pass a Ruby hash with symbol keys)
+html = "<h1>Hello</h1><p>This is <strong>fast</strong>!</p>"
 markdown = HtmlToMarkdown.convert(html, heading_style: :atx, code_block_style: :fenced)
+```
 
-# With inline images
-result = HtmlToMarkdown.convert_with_inline_images(html, image_config: {...})
-markdown = result.markdown
-images = result.inline_images
 
-# With metadata extraction
-markdown, metadata = HtmlToMarkdown.convert_with_metadata(html, options, metadata_config)
 
-# With visitor pattern (custom callbacks)
-result = HtmlToMarkdown.convert_with_visitor(html, visitor: MyVisitor.new, options: {...})
-```
 
-### Conversion Options Hash
 
-```ruby
-{
-  heading_style: :atx,                    # :atx or :setext
-  code_block_style: :fenced,              # :fenced or :indented
-  bullets: '*+-',                         # List bullet chars
-  list_indent_type: :spaces,              # :spaces or :tabs
-  list_indent_width: 2,                   # Number of indent spaces
-  whitespace_mode: :normalized,           # :normalized, :preserve, or :collapse
-  highlight_style: :double_equal,         # Code highlighting style
-  hocr_spatial_tables: false,             # Special hOCR table handling
-  preprocessing: {
-    enabled: true,
-    preset: :aggressive,                  # :minimal, :standard, :aggressive
-    remove_navigation: true,
-    remove_forms: true
-  }
-}
-```
 
-### Performance: Reusing Options
+## API Reference
 
-For tight loops, build an options handle once:
+### Core Functions
 
-```ruby
-handle = HtmlToMarkdown.options(hocr_spatial_tables: false)
 
-100.times do
-  HtmlToMarkdown.convert_with_options(html, handle)
-end
-```
+**`convert(html, options: nil) -> String`**
 
-### Metadata Extraction
+Basic HTML-to-Markdown conversion. Fast and simple.
 
-Extract document properties (title, description, author, language), social metadata (Open Graph, Twitter cards), heading hierarchy, link analysis, image metadata, and structured data (JSON-LD, Microdata, RDFa):
+**`convert_with_metadata(html, options: nil, config: nil) -> [String, Hash]`**
 
-```ruby
-html = '<html lang="en"><head><title>Test</title></head><body><h1>Hello</h1></body></html>'
-markdown, metadata = HtmlToMarkdown.convert_with_metadata(html)
+Extract Markdown plus metadata (headers, links, images, structured data) in a single pass. See [Metadata Extraction Guide](../../examples/metadata-extraction/).
 
-puts metadata[:document][:title]     # "Test"
-puts metadata[:headers].first[:text] # "Hello"
-```
+**`convert_with_visitor(html, visitor:, options: nil) -> String`**
 
-For detailed examples (SEO extraction, heading hierarchy analysis, structured data) and full metadata structure reference, see [Metadata Extraction Guide](../../examples/metadata-extraction/).
+Customize conversion with visitor callbacks for element interception. See [Visitor Pattern Guide](../../examples/visitor-pattern/).
 
-### Visitor Pattern
+**`convert_with_inline_images(html, config: nil) -> [String, Array, Array]`**
 
-Customize conversion with fine-grained element callbacks. Perfect for custom element handling, analytics during conversion, domain-specific markdown dialects, and conditional rendering:
+Extract base64-encoded inline images with metadata.
 
-```ruby
-class MyVisitor
-  def visit_link(ctx, href, text, title = nil)
-    { type: :custom, output: "[#{text}](#{href})" }
-  end
 
-  def visit_image(ctx, src, alt, title = nil)
-    { type: :skip }  # Remove images
-  end
-end
 
-result = HtmlToMarkdown.convert_with_visitor(html, visitor: MyVisitor.new)
-```
+### Options
 
-**Return types**: `{ type: :continue }` (default), `{ type: :custom, output: "..." }` (replace), `{ type: :skip }` (omit), `{ type: :preserve_html }` (keep HTML), `{ type: :error, message: "..." }` (halt).
+**`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`
 
-**40+ visitor methods** for text, inline formatting, blocks, lists, tables, advanced elements, and lifecycle hooks. Callback parameters include `NodeContext` with element metadata (tag_name, attributes, depth, parent_tag, is_inline).
+**`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`
 
-For advanced examples (image filtering, link analytics, footnote dialects), RBS type-safety patterns, and full method reference, see [Visitor Pattern Guide](../../examples/visitor-pattern/).
 
-## RBS Types & Strict Type Checking
 
-Full RBS type definitions in `sig/html_to_markdown.rbs` enable strict type checking with [Steep](https://github.com/soutaro/steep):
+## Metadata Extraction
 
-```bash
-steep check
-```
+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
 
-Key types:
-- `HtmlToMarkdown::NodeContext` - Element metadata in visitor callbacks (tag_name, attributes, depth, etc.)
-- `HtmlToMarkdown::visitor_result` - Return type union for visitor methods
-- `HtmlToMarkdown::extended_metadata` - Metadata extraction result
+**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
 
-Type-safe visitor implementation:
 
 ```ruby
-class TypedVisitor
-  def visit_link(
-    ctx : HtmlToMarkdown::NodeContext,
-    href : String,
-    text : String,
-    title : String | nil = nil
-  ) : HtmlToMarkdown::visitor_result
-    { type: :custom, output: "[#{text}](#{href})" }
-  end
-end
+require 'html_to_markdown'
+
+html = '<h1>Article</h1><img src="test.jpg" alt="test">'
+markdown, metadata = HtmlToMarkdown.convert_with_metadata(html)
+
+puts metadata[:document][:title]           # Document title
+puts metadata[:headers]                    # All h1-h6 elements
+puts metadata[:links]                      # All hyperlinks
+puts metadata[:images]                     # All images with alt text
+puts metadata[:structured_data]            # JSON-LD, Microdata, RDFa
 ```
 
-All public methods are typed for early error detection and LSP editor support (Ruby 3+).
 
-## Magnus Native Extension
 
-The gem compiles a native Rust extension via [Magnus](https://github.com/matsadler/magnus) FFI bindings:
+For detailed examples including SEO extraction, table-of-contents generation, link validation, and accessibility audits, see the [Metadata Extraction Guide](../../examples/metadata-extraction/).
 
-- **Zero-copy interop**: String and hash data flows directly between Ruby and Rust
-- **Safe bindings**: No segfaults; Rust's type system ensures memory safety
-- **Automatic error mapping**: Rust errors convert to Ruby exceptions with full context
-- **Native performance**: Compiled to `.so` (Linux/macOS) or `.dll` (Windows)
-- **Smart compilation**: Prebuilt binaries for common platforms; falls back to on-install compilation
 
-Build manually:
 
-```bash
-bundle exec rake compile
-```
 
-## CLI Proxy
+## 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
 
-Call the Rust CLI directly from Ruby or shell:
 
 ```ruby
-require 'html_to_markdown/cli'
+require 'html_to_markdown'
 
-HtmlToMarkdown::CLI.run(%w[--heading-style atx input.html], stdout: $stdout)
+class MyVisitor
+  def visit_link(ctx, href, text, title = nil)
+    # Rewrite CDN URLs
+    if href.start_with?('https://old-cdn.com')
+      href = href.sub('https://old-cdn.com', 'https://new-cdn.com')
+    end
+    { type: :custom, output: "[#{text}](#{href})" }
+  end
 
-# Or call the binary directly
-HtmlToMarkdown::CLIProxy.call(['--version'])
+  def visit_image(ctx, src, alt = nil, title = nil)
+    # Skip tracking pixels
+    src.include?('tracking') ? { type: :skip } : { type: :continue }
+  end
+end
+
+html = '<a href="https://old-cdn.com/file.pdf">Download</a>'
+markdown = HtmlToMarkdown.convert_with_visitor(html, visitor: MyVisitor.new)
 ```
 
-## Error Handling
 
-- `HtmlToMarkdown::Error` - Conversion errors with Rust error context
-- `HtmlToMarkdown::CLIProxy::MissingBinaryError` - CLI binary not found
-- `HtmlToMarkdown::CLIProxy::CLIExecutionError` - Command execution failed
 
-Binary data inputs (e.g., PDF bytes as string) raise `HtmlToMarkdown::Error` with "Invalid input" message.
+For comprehensive examples including content filtering, link footnotes, accessibility validation, and asynchronous URL validation, see the [Visitor Pattern Guide](../../examples/visitor-pattern/).
+
+
 
 ## Examples
 
-Comprehensive guides with real-world patterns (Ruby examples included):
+- [Visitor Pattern Guide](../../examples/visitor-pattern/)
+- [Metadata Extraction Guide](../../examples/metadata-extraction/)
+- [Performance Guide](../../examples/performance/)
 
-- **[Visitor Pattern](../../examples/visitor-pattern/)** - Custom callbacks, element-by-element control, analytics, domain-specific markdown dialects
-- **[Metadata Extraction](../../examples/metadata-extraction/)** - SEO data, heading hierarchy, link classification, structured data parsing
-- **[Performance Guide](../../examples/performance/)** - Benchmarking, profiling, throughput optimization
+## Links
 
-## Consistent Across Languages
+- **GitHub:** [github.com/kreuzberg-dev/html-to-markdown](https://github.com/kreuzberg-dev/html-to-markdown)
 
-The Ruby gem shares the exact Rust core with:
+- **RubyGems:** [rubygems.org/gems/html-to-markdown](https://rubygems.org/gems/html-to-markdown)
 
-- [Python wheels](https://pypi.org/project/html-to-markdown/)
-- [Node.js / Bun bindings](https://www.npmjs.com/package/html-to-markdown-node)
-- [WebAssembly package](https://www.npmjs.com/package/html-to-markdown-wasm)
-- [PHP extension](https://packagist.org/packages/goldziher/html-to-markdown)
-- The Rust crate and CLI
+- **Kreuzberg Ecosystem:** [kreuzberg.dev](https://kreuzberg.dev)
+- **Discord:** [discord.gg/pXxagNK2zN](https://discord.gg/pXxagNK2zN)
 
-Use whichever runtime fits your stack while keeping formatting behaviour identical.
+## Contributing
 
-## Development
+We welcome contributions! Please see our [Contributing Guide](https://github.com/kreuzberg-dev/html-to-markdown/blob/main/CONTRIBUTING.md) for details on:
 
-```bash
-bundle exec rake compile   # build the native extension
-bundle exec rspec          # run test suite
-```
+- 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):
 
-When editing Rust code under `src/`, rerun `rake compile`.
+- Proper test coverage (Rust 95%+, language bindings 80%+)
+- Formatting and linting checks
+- Documentation for public APIs
 
 ## License
 
-MIT © Na'aman Hirschfeld
+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)

data/ext/html-to-markdown-rb/native/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "html-to-markdown-rb"
-version = "2.18.0"
+version = "2.19.0"
 edition = "2024"
 authors = ["Na'aman Hirschfeld <nhirschfeld@gmail.com>"]
 license = "MIT"
@@ -18,7 +18,7 @@ name = "html_to_markdown_rb"
 crate-type = ["cdylib", "rlib"]
 
 [dependencies]
-html-to-markdown-rs = { version = "2.16.1", features = ["inline-images", "visitor", "metadata"] }
+html-to-markdown-rs = { version = "2.18.0", features = ["inline-images", "visitor", "metadata"] }
 magnus = { git = "https://github.com/matsadler/magnus", rev = "f6db11769efb517427bf7f121f9c32e18b059b38", features = ["rb-sys"] }
 
 [target.'cfg(not(target_os = "windows"))'.dependencies]

data/lib/html_to_markdown/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module HtmlToMarkdown
-  VERSION = '2.18.0'
+  VERSION = '2.19.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: html-to-markdown
 version: !ruby/object:Gem::Version
-  version: 2.18.0
+  version: 2.19.0
 platform: ruby
 authors:
 - Na'aman Hirschfeld
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-12-28 00:00:00.000000000 Z
+date: 2025-12-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rb_sys