html-to-markdown 2.30.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a59dd088c63edcda3711c276290e4377db037bd7a7cab8beb8bcbe83cf52a6f7
-  data.tar.gz: f49297af30be7e708bbca200099d471dbaadc0c98b2916489f17e83c07644ba7
+  metadata.gz: 823ad44845a919191f6b64697599dab71cd1a6e0d6a9a1f222fa0500ef66eb9a
+  data.tar.gz: 360148ff88f88e404ef19f14baccec24b0fa2dfe21b5f601ffc2ae56a9420f52
 SHA512:
-  metadata.gz: 94a8a04d0c146886a27c184ec5aacd83ed1619611b6666d9a98e3088c1fae5421b38a7b83dc557decb14a49e05f2b70d9ae142d3db61ab8dbf2bde165ee67dcc
-  data.tar.gz: b6676434b9dcf908f84d1803de65e2bbc86c4413eae4bd861d7732acca3b6938f9184ffb6b6e32b5326e7f56003fd44c67b851863f3b63931b69a388fb2bcfa6
+  metadata.gz: 664d63d8e57a17085da777089fff023db75b840f686ea84e12d9529bedc8d0405c4c9027f565d7c5cc8a5e01e42d3e7d81c356668b858f1f22451dd80349bceb
+  data.tar.gz: cd46a114ee8a200cbfa42e653b4ca24a2a2ef884c4981d366ab01dbd23e2bdc13f304bf12c9d6b367b480c3bca5e4e98f82805a8862320ac40931a42904b5ee6

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    html-to-markdown (2.30.0)
+    html-to-markdown (3.0.0)
       rb_sys (>= 0.9, < 1.0)
 
 GEM
@@ -22,16 +22,13 @@ GEM
       uri (>= 0.13.1)
     ast (2.4.3)
     base64 (0.3.0)
-    bigdecimal (4.0.1)
+    bigdecimal (4.1.0)
     concurrent-ruby (1.3.6)
     connection_pool (3.0.2)
     csv (3.3.5)
     diff-lcs (1.6.2)
     drb (2.2.3)
-    ffi (1.17.4-aarch64-linux-gnu)
     ffi (1.17.4-arm64-darwin)
-    ffi (1.17.4-x64-mingw-ucrt)
-    ffi (1.17.4-x86_64-darwin)
     ffi (1.17.4-x86_64-linux-gnu)
     fileutils (1.8.0)
     i18n (1.14.8)
@@ -129,12 +126,8 @@ GEM
     uri (1.1.1)
 
 PLATFORMS
-  aarch64-linux
   arm64-darwin
-  x64-mingw-ucrt
-  x86_64-darwin
   x86_64-linux
-  x86_64-linux-gnu
 
 DEPENDENCIES
   html-to-markdown!
@@ -150,19 +143,16 @@ CHECKSUMS
   activesupport (8.1.3) sha256=21a5e0dfbd4c3ddd9e1317ec6a4d782fa226e7867dc70b0743acda81a1dca20e
   ast (2.4.3) sha256=954615157c1d6a382bc27d690d973195e79db7f55e9765ac7c481c60bdb4d383
   base64 (0.3.0) sha256=27337aeabad6ffae05c265c450490628ef3ebd4b67be58257393227588f5a97b
-  bigdecimal (4.0.1) sha256=8b07d3d065a9f921c80ceaea7c9d4ae596697295b584c296fe599dd0ad01c4a7
+  bigdecimal (4.1.0) sha256=6dc07767aa3dc456ccd48e7ae70a07b474e9afd7c5bc576f80bd6da5c8dd6cae
   concurrent-ruby (1.3.6) sha256=6b56837e1e7e5292f9864f34b69c5a2cbc75c0cf5338f1ce9903d10fa762d5ab
   connection_pool (3.0.2) sha256=33fff5ba71a12d2aa26cb72b1db8bba2a1a01823559fb01d29eb74c286e62e0a
   csv (3.3.5) sha256=6e5134ac3383ef728b7f02725d9872934f523cb40b961479f69cf3afa6c8e73f
   diff-lcs (1.6.2) sha256=9ae0d2cba7d4df3075fe8cd8602a8604993efc0dfa934cff568969efb1909962
   drb (2.2.3) sha256=0b00d6fdb50995fe4a45dea13663493c841112e4068656854646f418fda13373
-  ffi (1.17.4-aarch64-linux-gnu) sha256=b208f06f91ffd8f5e1193da3cae3d2ccfc27fc36fba577baf698d26d91c080df
   ffi (1.17.4-arm64-darwin) sha256=19071aaf1419251b0a46852abf960e77330a3b334d13a4ab51d58b31a937001b
-  ffi (1.17.4-x64-mingw-ucrt) sha256=f6ff9618cfccc494138bddade27aa06c74c6c7bc367a1ea1103d80c2fcb9ed35
-  ffi (1.17.4-x86_64-darwin) sha256=aa70390523cf3235096cf64962b709b4cfbd5c082a2cb2ae714eb0fe2ccda496
   ffi (1.17.4-x86_64-linux-gnu) sha256=9d3db14c2eae074b382fa9c083fe95aec6e0a1451da249eab096c34002bc752d
   fileutils (1.8.0) sha256=8c6b1df54e2540bdb2f39258f08af78853aa70bad52b4d394bbc6424593c6e02
-  html-to-markdown (2.30.0)
+  html-to-markdown (3.0.0)
   i18n (1.14.8) sha256=285778639134865c5e0f6269e0b818256017e8cde89993fdfcbfb64d088824a5
   json (2.19.3) sha256=289b0bb53052a1fa8c34ab33cc750b659ba14a5c45f3fcf4b18762dc67c78646
   language_server-protocol (3.17.0.5) sha256=fd1e39a51a28bf3eec959379985a72e296e9f9acfce46f6a79d31ca8760803cc

data/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.29.0" 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#">
@@ -87,7 +87,6 @@ Apple M4 • Real Wikipedia documents • `convert()` (Ruby)
 | Mixed (Python wiki) | 656KB | 4.89ms | 134 MB/s |
 
 
-See [Performance Guide](../../examples/performance/) for detailed benchmarks.
 
 
 ## Quick Start
@@ -98,7 +97,8 @@ Basic conversion:
 require 'html_to_markdown'
 
 html = "<h1>Hello</h1><p>This is <strong>fast</strong>!</p>"
-markdown = HtmlToMarkdown.convert(html)
+result = HtmlToMarkdown.convert(html)
+markdown = result[:content]
 ```
 
 
@@ -109,60 +109,50 @@ With conversion options:
 require 'html_to_markdown'
 
 html = "<h1>Hello</h1><p>This is <strong>fast</strong>!</p>"
-markdown = HtmlToMarkdown.convert(html, heading_style: :atx, code_block_style: :fenced)
+result = HtmlToMarkdown.convert(html, heading_style: :atx, code_block_style: :fenced)
+markdown = result[:content]
 ```
 
 
 
 
-
-
 ## API Reference
 
-### Core Functions
-
-
-**`convert(html, options: nil) -> String`**
+### Core Function
 
-Basic HTML-to-Markdown conversion. Fast and simple.
 
-**`convert_with_metadata(html, options: nil, config: nil) -> [String, Hash]`**
+**`convert(html, options: nil, visitor: nil) -> ConversionResult`**
 
-Extract Markdown plus metadata (headers, links, images, structured data) in a single pass. See [Metadata Extraction Guide](../../examples/metadata-extraction/).
+Converts HTML to Markdown. Returns a `ConversionResult` hash with all results in a single call.
 
-**`convert_with_visitor(html, visitor:, options: nil) -> String`**
-
-Customize conversion with visitor callbacks for element interception. See [Visitor Pattern Guide](../../examples/visitor-pattern/).
-
-**`convert_with_inline_images(html, config: nil) -> [String, Array, Array]`**
-
-Extract base64-encoded inline images with metadata.
-
-**`convert_with_tables(html, options: nil, config: nil) -> ConversionWithTables`**
+```ruby
+require 'html_to_markdown'
 
-Extract structured table data (cells, headers, rendered markdown) alongside conversion.
+result = HtmlToMarkdown.convert(html)
+markdown = result[:content]       # Converted Markdown string
+metadata = result[:metadata]      # Metadata (when extract_metadata: true)
+tables   = result[:tables]        # Structured table data (when extract_tables: true)
+document = result[:document]      # Document-level info
+images   = result[:images]        # Extracted images
+warnings = result[:warnings]      # Any conversion warnings
+```
 
 
 
 ### Options
 
 **`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`
+- `extract_metadata`: Enable metadata extraction into `result.metadata` — default: `false`
+- `extract_tables`: Enable structured table extraction into `result.tables` — default: `false`
 - `output_format`: Output markup format (`"markdown"` | `"djot"` | `"plain"`) — default: `"markdown"`
 
-**`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`
-
 
 ## Djot Output Format
 
@@ -222,16 +212,17 @@ Plain text mode is useful for search indexing, text extraction, and feeding cont
 
 ## 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.
+The metadata extraction feature enables comprehensive document analysis during conversion. Extract document properties, headers, links, images, and structured data in a single pass — all via the standard `convert()` function.
 
 **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.
+**Zero Overhead When Disabled:** Metadata extraction adds negligible overhead and happens during the HTML parsing pass. Pass `extract_metadata: true` in `ConversionOptions` to enable it; the result is available at `result.metadata`.
 
 ### Example: Quick Start
 
@@ -240,27 +231,27 @@ The metadata extraction feature enables comprehensive document analysis during c
 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
+result = HtmlToMarkdown.convert(html, extract_metadata: true)
+
+puts result[:content]                             # Converted Markdown
+puts result[:metadata][:document][:title]         # Document title
+puts result[:metadata][:headers]                  # All h1-h6 elements
+puts result[:metadata][:links]                    # All hyperlinks
+puts result[:metadata][:images]                   # All images with alt text
+puts result[:metadata][:structured_data]          # JSON-LD, Microdata, RDFa
 ```
 
 
 
-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.
+The visitor pattern enables custom HTML→Markdown conversion logic by providing callbacks for specific HTML elements during traversal. Pass a visitor as the third argument to `convert()`.
 
 **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
@@ -291,20 +282,16 @@ class MyVisitor
 end
 
 html = '<a href="https://old-cdn.com/file.pdf">Download</a>'
-markdown = HtmlToMarkdown.convert_with_visitor(html, visitor: MyVisitor.new)
+result = HtmlToMarkdown.convert(html, visitor: MyVisitor.new)
+markdown = result[:content]
 ```
 
 
 
-For comprehensive examples including content filtering, link footnotes, accessibility validation, and asynchronous URL validation, see the [Visitor Pattern Guide](../../examples/visitor-pattern/).
-
 
 
 ## Examples
 
-- [Visitor Pattern Guide](../../examples/visitor-pattern/)
-- [Metadata Extraction Guide](../../examples/metadata-extraction/)
-- [Performance Guide](../../examples/performance/)
 
 ## Links