html-to-markdown 2.6.5 → 2.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 32f9140116181176bc78edbbe936ecbb679656734cc205e46a2f1e0717068f72
-  data.tar.gz: 3eaaa3b6bc8332df402a2f5405460d28d5176edb18216b7afaa7cae634ce64d7
+  metadata.gz: 56ca0b6b6d1c9e67dadddfa1865e693bcf986859cc203f7987a5f787203ff40f
+  data.tar.gz: 932a473d64548a6d976c452b4d82a357e10709f7975a43e5d699e543a9d3a372
 SHA512:
-  metadata.gz: c9fca57c280d7c413b9789a550e598741bda9151bf02e5991b1ffa8b42a1f75940621d62e75b0eb13c24646c22e71fe316cbd9ebc77324f7486d6a8773fcc456
-  data.tar.gz: 162a253371ec62b6854173eb1559986b127a16fb5655cf2c26e2ef6ae5f4e80bc1f222bdfe6d8ada87c53871f24982c35f24606bc1fcf0a335d4dcd2e9566fba
+  metadata.gz: 0e36518ae77b2c25f0ac0c26686524d152c687a026fc0f2f4c7b3ed03bd219cc8a5a799ddb8f9b698a5d3e64db7d05ac7d936b535b797aafd806a276af97e993
+  data.tar.gz: 31ab40f1ff1daae0e2b06e485e3e85d15f59fca17c07a8b6b64785b2326e9a6d208381183b043dcac92e01c83fd98b6a8607438faffb2b1e01d4953cb96e19f0

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    html-to-markdown (2.6.5)
+    html-to-markdown (2.7.0)
       rb_sys (>= 0.9, < 1.0)
 
 GEM
@@ -50,7 +50,7 @@ GEM
       rubocop-ast (>= 1.47.1, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.47.1)
+    rubocop-ast (1.48.0)
       parser (>= 3.3.7.2)
       prism (~> 1.4)
     rubocop-rspec (3.7.0)

data/README.md

@@ -1,11 +1,10 @@
 # html-to-markdown-rb
 
-Blazing-fast HTML → Markdown conversion for Ruby, powered by the same Rust engine used by our Python, Node.js, and WebAssembly packages. Ship identical Markdown across every runtime while enjoying native extension performance.
+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)](https://crates.io/crates/html-to-markdown-rs)
 [![npm (node)](https://badge.fury.io/js/html-to-markdown-node.svg)](https://www.npmjs.com/package/html-to-markdown-node)
 [![npm (wasm)](https://badge.fury.io/js/html-to-markdown-wasm.svg)](https://www.npmjs.com/package/html-to-markdown-wasm)
-[![npm (typescript)](https://badge.fury.io/js/html-to-markdown.svg)](https://www.npmjs.com/package/html-to-markdown)
 [![PyPI](https://badge.fury.io/py/html-to-markdown.svg)](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)
@@ -14,7 +13,7 @@ Blazing-fast HTML → Markdown conversion for Ruby, powered by the same Rust eng
 ## 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, WASM package, and CLI — consistent Markdown everywhere.
+- 🔁 **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.
@@ -110,6 +109,18 @@ markdown = HtmlToMarkdown.convert(
 puts markdown
 ```
 
+### Reusing Options
+
+If you’re running tight loops or benchmarks, build the options once and pass the handle back into `convert_with_options`:
+
+```ruby
+handle = HtmlToMarkdown.options(hocr_spatial_tables: false)
+
+100.times do
+  HtmlToMarkdown.convert_with_options('<h1>Handles</h1>', handle)
+end
+```
+
 ### HTML Preprocessing
 
 Clean up scraped HTML (navigation, forms, malformed markup) before conversion:

data/bin/benchmark.rb

@@ -0,0 +1,94 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'optparse'
+require 'time'
+
+$LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
+require 'html_to_markdown'
+
+def json_escape(value)
+  value.to_s.gsub(/["\\\n\r]/) do |char|
+    case char
+    when '"', '\\'
+      "\\#{char}"
+    when "\n"
+      '\\n'
+    when "\r"
+      '\\r'
+    end
+  end
+end
+
+options = {
+  iterations: 50,
+  format: 'html'
+}
+
+OptionParser.new do |parser|
+  parser.banner = 'ruby benchmark.rb --file path/to/fixture.html [--iterations 200]'
+
+  parser.on('--file FILE', 'HTML fixture to convert repeatedly') do |file|
+    options[:file] = file
+  end
+
+  parser.on('--iterations N', Integer, 'Number of conversion iterations (default: 50)') do |n|
+    options[:iterations] = n.positive? ? n : 1
+  end
+
+  parser.on('--format FORMAT', 'Fixture format (html or hocr)') do |format|
+    options[:format] = format.downcase
+  end
+end.parse!
+
+fixture = options.fetch(:file) do
+  warn 'Missing --file parameter'
+  exit 1
+end
+
+unless File.exist?(fixture)
+  warn "Fixture not found: #{fixture}"
+  exit 1
+end
+
+unless %w[html hocr].include?(options[:format])
+  warn "Unsupported format: #{options[:format]}"
+  exit 1
+end
+
+html = File.binread(fixture)
+html.force_encoding(Encoding::UTF_8)
+html.freeze
+iterations = options[:iterations]
+options_handle = HtmlToMarkdown.options(
+  options[:format] == 'hocr' ? { hocr_spatial_tables: false } : nil
+)
+
+def convert_document(html, options_handle)
+  HtmlToMarkdown.convert_with_options(html, options_handle)
+end
+
+convert_document(html, options_handle)
+
+start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+iterations.times { convert_document(html, options_handle) }
+elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start
+
+payload_size_bytes = html.bytesize
+bytes_processed = payload_size_bytes * iterations
+ops_per_sec = iterations / elapsed
+mb_per_sec = (bytes_processed.to_f / (1024 * 1024)) / elapsed
+
+payload = %({
+  "language":"ruby",
+  "fixture":"#{json_escape(File.basename(fixture))}",
+  "fixture_path":"#{json_escape(fixture)}",
+  "iterations":#{iterations},
+  "elapsed_seconds":#{format('%.8f', elapsed)},
+  "ops_per_sec":#{format('%.4f', ops_per_sec)},
+  "mb_per_sec":#{format('%.4f', mb_per_sec)},
+  "bytes_processed":#{bytes_processed},
+  "payload_size_bytes":#{payload_size_bytes}
+})
+
+puts payload.strip

data/ext/html-to-markdown-rb/extconf.rb

@@ -24,5 +24,5 @@ default_profile = ENV.fetch('CARGO_PROFILE', 'release')
 
 create_rust_makefile('html_to_markdown_rb') do |config|
   config.profile = default_profile.to_sym
-  config.ext_dir = '../../../../crates/html-to-markdown-rb'
+  config.ext_dir = File.expand_path('native', __dir__)
 end

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

@@ -0,0 +1,28 @@
+[package]
+name = "html-to-markdown-rb"
+version = "2.7.0"
+edition.workspace = true
+authors = ["Na'aman Hirschfeld <nhirschfeld@gmail.com>"]
+license = "MIT"
+repository = "https://github.com/Goldziher/html-to-markdown"
+homepage = "https://github.com/Goldziher/html-to-markdown"
+documentation = "https://docs.rs/html-to-markdown-rs"
+readme = "README.md"
+rust-version.workspace = true
+description = "Ruby bindings (Magnus) for html-to-markdown - high-performance HTML to Markdown converter"
+keywords = ["html", "markdown", "ruby", "magnus", "bindings"]
+categories = ["api-bindings"]
+
+[lib]
+name = "html_to_markdown_rb"
+crate-type = ["cdylib", "rlib"]
+
+[features]
+default = []
+
+[dependencies]
+html-to-markdown-rs = { version = "2.7.0", features = ["inline-images"] }
+magnus = { git = "https://github.com/matsadler/magnus", rev = "f6db11769efb517427bf7f121f9c32e18b059b38", features = ["rb-sys"] }
+
+[dev-dependencies]
+pretty_assertions = "1.4"

data/ext/html-to-markdown-rb/native/README.md

@@ -0,0 +1,209 @@
+# 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)](https://crates.io/crates/html-to-markdown-rs)
+[![npm (node)](https://badge.fury.io/js/html-to-markdown-node.svg)](https://www.npmjs.com/package/html-to-markdown-node)
+[![npm (wasm)](https://badge.fury.io/js/html-to-markdown-wasm.svg)](https://www.npmjs.com/package/html-to-markdown-wasm)
+[![PyPI](https://badge.fury.io/py/html-to-markdown.svg)](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)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/Goldziher/html-to-markdown/blob/main/LICENSE)
+
+## 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/Goldziher/html-to-markdown)
+- [Issue tracker](https://github.com/Goldziher/html-to-markdown/issues)
+- [Changelog](https://github.com/Goldziher/html-to-markdown/blob/main/CHANGELOG.md)
+- [Live demo (WASM)](https://goldziher.github.io/html-to-markdown/)
+
+## 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)
+
+**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 • `HtmlToMarkdown.convert` (Ruby)
+
+| Document            | Size  | Latency | Throughput | Docs/sec |
+| ------------------- | ----- | ------- | ---------- | -------- |
+| Lists (Timeline)    | 129KB | 0.69ms  | 187 MB/s   | 1,450    |
+| Tables (Countries)  | 360KB | 2.19ms  | 164 MB/s   | 456      |
+| Mixed (Python wiki) | 656KB | 4.88ms  | 134 MB/s   | 205      |
+
+> Same core, same benchmarks: the Ruby extension stays within single-digit % of the Rust CLI and mirrors the Python/Node numbers.
+
+## Quick Start
+
+```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
+
+markdown = HtmlToMarkdown.convert(html)
+puts markdown
+# # Welcome
+#
+# This is **Rust-fast** conversion!
+#
+# - Native extension
+# - Identical output across languages
+```
+
+## API
+
+### Conversion Options
+
+Pass a Ruby hash (string or symbol keys) to tweak rendering. Every option maps one-for-one with the Rust/Python/Node APIs.
+
+```ruby
+require 'html_to_markdown'
+
+markdown = HtmlToMarkdown.convert(
+  '<pre><code class="language-ruby">puts "hi"</code></pre>',
+  heading_style: :atx,
+  code_block_style: :fenced,
+  bullets: '*+-',
+  list_indent_type: :spaces,
+  list_indent_width: 2,
+  whitespace_mode: :normalized,
+  highlight_style: :double_equal
+)
+
+puts markdown
+```
+
+### HTML Preprocessing
+
+Clean up scraped HTML (navigation, forms, malformed markup) before conversion:
+
+```ruby
+require 'html_to_markdown'
+
+markdown = HtmlToMarkdown.convert(
+  html,
+  preprocessing: {
+    enabled: true,
+    preset: :aggressive, # :minimal, :standard, :aggressive
+    remove_navigation: true,
+    remove_forms: true
+  }
+)
+```
+
+### Inline Images
+
+Extract inline binary data (data URIs, SVG) together with the converted Markdown.
+
+```ruby
+require 'html_to_markdown'
+
+result = HtmlToMarkdown.convert_with_inline_images(
+  '<img src="data:image/png;base64,iVBORw0..." alt="Pixel">',
+  image_config: {
+    max_decoded_size_bytes: 1 * 1024 * 1024,
+    infer_dimensions: true,
+    filename_prefix: 'img_',
+    capture_svg: true
+  }
+)
+
+puts result.markdown
+result.inline_images.each do |img|
+  puts "#{img.filename} -> #{img.format} (#{img.data.bytesize} bytes)"
+end
+```
+
+## CLI
+
+The gem bundles a small proxy for the Rust CLI binary. Use it when you need parity with the standalone `html-to-markdown` executable.
+
+```ruby
+require 'html_to_markdown/cli'
+
+HtmlToMarkdown::CLI.run(%w[--heading-style atx input.html], stdout: $stdout)
+# => writes converted Markdown to STDOUT
+```
+
+You can also call the CLI binary directly for scripting:
+
+```ruby
+HtmlToMarkdown::CLIProxy.call(['--version'])
+# => "html-to-markdown 2.5.7"
+```
+
+Rebuild the CLI locally if you see `CLI binary not built` during tests:
+
+```bash
+bundle exec rake compile          # builds the extension
+bundle exec ruby scripts/prepare_ruby_gem.rb  # copies the CLI into lib/bin/
+```
+
+## Error Handling
+
+Conversion errors raise `HtmlToMarkdown::Error` (wrapping the Rust error context). CLI invocations use specialised subclasses:
+
+- `HtmlToMarkdown::CLIProxy::MissingBinaryError`
+- `HtmlToMarkdown::CLIProxy::CLIExecutionError`
+
+Rescue them to provide clearer feedback in your application.
+
+## Consistent Across Languages
+
+The Ruby gem shares the exact Rust core with:
+
+- [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)
+- The Rust crate and CLI
+
+Use whichever runtime fits your stack while keeping formatting behaviour identical.
+
+## Development
+
+```bash
+bundle exec rake compile   # build the native extension
+bundle exec rspec          # run test suite
+```
+
+The extension uses [Magnus](https://github.com/matsadler/magnus) plus `rb-sys` for bindgen. When editing the Rust code under `src/`, rerun `rake compile`.
+
+## License
+
+MIT © Na'aman Hirschfeld

data/ext/html-to-markdown-rb/native/extconf.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative '../extconf'

data/ext/html-to-markdown-rb/native/src/lib.rs

@@ -0,0 +1,432 @@
+use html_to_markdown_rs::{
+    CodeBlockStyle, ConversionOptions, HeadingStyle, HighlightStyle, HtmlExtraction, InlineImage, InlineImageConfig,
+    InlineImageFormat, InlineImageSource, InlineImageWarning, ListIndentType, NewlineStyle, PreprocessingOptions,
+    PreprocessingPreset, WhitespaceMode, convert as convert_inner,
+    convert_with_inline_images as convert_with_inline_images_inner, error::ConversionError,
+};
+use magnus::prelude::*;
+use magnus::r_hash::ForEach;
+use magnus::{Error, RArray, RHash, Ruby, Symbol, TryConvert, Value, function, scan_args::scan_args};
+
+#[derive(Clone)]
+#[magnus::wrap(class = "HtmlToMarkdown::Options", free_immediately)]
+struct OptionsHandle(ConversionOptions);
+
+const DEFAULT_INLINE_IMAGE_LIMIT: u64 = 5 * 1024 * 1024;
+
+fn conversion_error(err: ConversionError) -> Error {
+    match err {
+        ConversionError::ConfigError(msg) => arg_error(msg),
+        other => runtime_error(other.to_string()),
+    }
+}
+
+fn arg_error(message: impl Into<String>) -> Error {
+    let ruby = Ruby::get().expect("Ruby not initialised");
+    Error::new(ruby.exception_arg_error(), message.into())
+}
+
+fn runtime_error(message: impl Into<String>) -> Error {
+    let ruby = Ruby::get().expect("Ruby not initialised");
+    Error::new(ruby.exception_runtime_error(), message.into())
+}
+
+fn symbol_to_string(value: Value) -> Result<String, Error> {
+    if let Some(symbol) = Symbol::from_value(value) {
+        Ok(symbol.name()?.to_string())
+    } else {
+        String::try_convert(value)
+    }
+}
+
+fn parse_heading_style(value: Value) -> Result<HeadingStyle, Error> {
+    match symbol_to_string(value)?.as_str() {
+        "underlined" => Ok(HeadingStyle::Underlined),
+        "atx" => Ok(HeadingStyle::Atx),
+        "atx_closed" => Ok(HeadingStyle::AtxClosed),
+        other => Err(arg_error(format!("invalid heading_style: {other}"))),
+    }
+}
+
+fn parse_list_indent_type(value: Value) -> Result<ListIndentType, Error> {
+    match symbol_to_string(value)?.as_str() {
+        "spaces" => Ok(ListIndentType::Spaces),
+        "tabs" => Ok(ListIndentType::Tabs),
+        other => Err(arg_error(format!("invalid list_indent_type: {other}"))),
+    }
+}
+
+fn parse_highlight_style(value: Value) -> Result<HighlightStyle, Error> {
+    match symbol_to_string(value)?.as_str() {
+        "double_equal" => Ok(HighlightStyle::DoubleEqual),
+        "html" => Ok(HighlightStyle::Html),
+        "bold" => Ok(HighlightStyle::Bold),
+        "none" => Ok(HighlightStyle::None),
+        other => Err(arg_error(format!("invalid highlight_style: {other}"))),
+    }
+}
+
+fn parse_whitespace_mode(value: Value) -> Result<WhitespaceMode, Error> {
+    match symbol_to_string(value)?.as_str() {
+        "normalized" => Ok(WhitespaceMode::Normalized),
+        "strict" => Ok(WhitespaceMode::Strict),
+        other => Err(arg_error(format!("invalid whitespace_mode: {other}"))),
+    }
+}
+
+fn parse_newline_style(value: Value) -> Result<NewlineStyle, Error> {
+    match symbol_to_string(value)?.as_str() {
+        "spaces" => Ok(NewlineStyle::Spaces),
+        "backslash" => Ok(NewlineStyle::Backslash),
+        other => Err(arg_error(format!("invalid newline_style: {other}"))),
+    }
+}
+
+fn parse_code_block_style(value: Value) -> Result<CodeBlockStyle, Error> {
+    match symbol_to_string(value)?.as_str() {
+        "indented" => Ok(CodeBlockStyle::Indented),
+        "backticks" => Ok(CodeBlockStyle::Backticks),
+        "tildes" => Ok(CodeBlockStyle::Tildes),
+        other => Err(arg_error(format!("invalid code_block_style: {other}"))),
+    }
+}
+
+fn parse_preset(value: Value) -> Result<PreprocessingPreset, Error> {
+    match symbol_to_string(value)?.as_str() {
+        "minimal" => Ok(PreprocessingPreset::Minimal),
+        "standard" => Ok(PreprocessingPreset::Standard),
+        "aggressive" => Ok(PreprocessingPreset::Aggressive),
+        other => Err(arg_error(format!("invalid preprocessing preset: {other}"))),
+    }
+}
+
+fn parse_vec_of_strings(value: Value) -> Result<Vec<String>, Error> {
+    let array = RArray::from_value(value).ok_or_else(|| arg_error("expected an Array of strings"))?;
+
+    array.to_vec::<String>()
+}
+
+fn parse_preprocessing_options(_ruby: &Ruby, value: Value) -> Result<PreprocessingOptions, Error> {
+    let hash = RHash::from_value(value).ok_or_else(|| arg_error("expected preprocessing to be a Hash"))?;
+
+    let mut opts = PreprocessingOptions::default();
+
+    hash.foreach(|key: Value, val: Value| {
+        let key_name = symbol_to_string(key)?;
+        match key_name.as_str() {
+            "enabled" => {
+                opts.enabled = bool::try_convert(val)?;
+            }
+            "preset" => {
+                opts.preset = parse_preset(val)?;
+            }
+            "remove_navigation" => {
+                opts.remove_navigation = bool::try_convert(val)?;
+            }
+            "remove_forms" => {
+                opts.remove_forms = bool::try_convert(val)?;
+            }
+            _ => {}
+        }
+        Ok(ForEach::Continue)
+    })?;
+
+    Ok(opts)
+}
+
+fn build_conversion_options(ruby: &Ruby, options: Option<Value>) -> Result<ConversionOptions, Error> {
+    let mut opts = ConversionOptions::default();
+
+    let Some(options) = options else {
+        return Ok(opts);
+    };
+
+    if options.is_nil() {
+        return Ok(opts);
+    }
+
+    let hash = RHash::from_value(options).ok_or_else(|| arg_error("options must be provided as a Hash"))?;
+
+    hash.foreach(|key: Value, val: Value| {
+        let key_name = symbol_to_string(key)?;
+        match key_name.as_str() {
+            "heading_style" => {
+                opts.heading_style = parse_heading_style(val)?;
+            }
+            "list_indent_type" => {
+                opts.list_indent_type = parse_list_indent_type(val)?;
+            }
+            "list_indent_width" => {
+                opts.list_indent_width = usize::try_convert(val)?;
+            }
+            "bullets" => {
+                opts.bullets = String::try_convert(val)?;
+            }
+            "strong_em_symbol" => {
+                let value = String::try_convert(val)?;
+                let mut chars = value.chars();
+                let ch = chars
+                    .next()
+                    .ok_or_else(|| arg_error("strong_em_symbol must not be empty"))?;
+                if chars.next().is_some() {
+                    return Err(arg_error("strong_em_symbol must be a single character"));
+                }
+                opts.strong_em_symbol = ch;
+            }
+            "escape_asterisks" => {
+                opts.escape_asterisks = bool::try_convert(val)?;
+            }
+            "escape_underscores" => {
+                opts.escape_underscores = bool::try_convert(val)?;
+            }
+            "escape_misc" => {
+                opts.escape_misc = bool::try_convert(val)?;
+            }
+            "escape_ascii" => {
+                opts.escape_ascii = bool::try_convert(val)?;
+            }
+            "code_language" => {
+                opts.code_language = String::try_convert(val)?;
+            }
+            "autolinks" => {
+                opts.autolinks = bool::try_convert(val)?;
+            }
+            "default_title" => {
+                opts.default_title = bool::try_convert(val)?;
+            }
+            "br_in_tables" => {
+                opts.br_in_tables = bool::try_convert(val)?;
+            }
+            "hocr_spatial_tables" => {
+                opts.hocr_spatial_tables = bool::try_convert(val)?;
+            }
+            "highlight_style" => {
+                opts.highlight_style = parse_highlight_style(val)?;
+            }
+            "extract_metadata" => {
+                opts.extract_metadata = bool::try_convert(val)?;
+            }
+            "whitespace_mode" => {
+                opts.whitespace_mode = parse_whitespace_mode(val)?;
+            }
+            "strip_newlines" => {
+                opts.strip_newlines = bool::try_convert(val)?;
+            }
+            "wrap" => {
+                opts.wrap = bool::try_convert(val)?;
+            }
+            "wrap_width" => {
+                opts.wrap_width = usize::try_convert(val)?;
+            }
+            "convert_as_inline" => {
+                opts.convert_as_inline = bool::try_convert(val)?;
+            }
+            "sub_symbol" => {
+                opts.sub_symbol = String::try_convert(val)?;
+            }
+            "sup_symbol" => {
+                opts.sup_symbol = String::try_convert(val)?;
+            }
+            "newline_style" => {
+                opts.newline_style = parse_newline_style(val)?;
+            }
+            "code_block_style" => {
+                opts.code_block_style = parse_code_block_style(val)?;
+            }
+            "keep_inline_images_in" => {
+                opts.keep_inline_images_in = parse_vec_of_strings(val)?;
+            }
+            "preprocessing" => {
+                opts.preprocessing = parse_preprocessing_options(ruby, val)?;
+            }
+            "encoding" => {
+                opts.encoding = String::try_convert(val)?;
+            }
+            "debug" => {
+                opts.debug = bool::try_convert(val)?;
+            }
+            "strip_tags" => {
+                opts.strip_tags = parse_vec_of_strings(val)?;
+            }
+            "preserve_tags" => {
+                opts.preserve_tags = parse_vec_of_strings(val)?;
+            }
+            _ => {}
+        }
+        Ok(ForEach::Continue)
+    })?;
+
+    Ok(opts)
+}
+
+fn build_inline_image_config(_ruby: &Ruby, config: Option<Value>) -> Result<InlineImageConfig, Error> {
+    let mut cfg = InlineImageConfig::new(DEFAULT_INLINE_IMAGE_LIMIT);
+
+    let Some(config) = config else {
+        return Ok(cfg);
+    };
+
+    if config.is_nil() {
+        return Ok(cfg);
+    }
+
+    let hash = RHash::from_value(config).ok_or_else(|| arg_error("inline image config must be provided as a Hash"))?;
+
+    hash.foreach(|key: Value, val: Value| {
+        let key_name = symbol_to_string(key)?;
+        match key_name.as_str() {
+            "max_decoded_size_bytes" => {
+                cfg.max_decoded_size_bytes = u64::try_convert(val)?;
+            }
+            "filename_prefix" => {
+                cfg.filename_prefix = if val.is_nil() {
+                    None
+                } else {
+                    Some(String::try_convert(val)?)
+                };
+            }
+            "capture_svg" => {
+                cfg.capture_svg = bool::try_convert(val)?;
+            }
+            "infer_dimensions" => {
+                cfg.infer_dimensions = bool::try_convert(val)?;
+            }
+            _ => {}
+        }
+        Ok(ForEach::Continue)
+    })?;
+
+    Ok(cfg)
+}
+
+fn inline_image_to_value(ruby: &Ruby, image: InlineImage) -> Result<Value, Error> {
+    let InlineImage {
+        data,
+        format,
+        filename,
+        description,
+        dimensions,
+        source,
+        attributes,
+    } = image;
+
+    let hash = ruby.hash_new();
+    let data_value = ruby.str_from_slice(&data);
+    hash.aset(ruby.intern("data"), data_value)?;
+
+    let format_value = match format {
+        InlineImageFormat::Png => "png".to_string(),
+        InlineImageFormat::Jpeg => "jpeg".to_string(),
+        InlineImageFormat::Gif => "gif".to_string(),
+        InlineImageFormat::Bmp => "bmp".to_string(),
+        InlineImageFormat::Webp => "webp".to_string(),
+        InlineImageFormat::Svg => "svg".to_string(),
+        InlineImageFormat::Other(other) => other,
+    };
+    hash.aset(ruby.intern("format"), format_value)?;
+
+    match filename {
+        Some(name) => hash.aset(ruby.intern("filename"), name)?,
+        None => hash.aset(ruby.intern("filename"), ruby.qnil())?,
+    }
+
+    match description {
+        Some(desc) => hash.aset(ruby.intern("description"), desc)?,
+        None => hash.aset(ruby.intern("description"), ruby.qnil())?,
+    }
+
+    if let Some((width, height)) = dimensions {
+        let dims = ruby.ary_new();
+        dims.push(width as i64)?;
+        dims.push(height as i64)?;
+        hash.aset(ruby.intern("dimensions"), dims)?;
+    } else {
+        hash.aset(ruby.intern("dimensions"), ruby.qnil())?;
+    }
+
+    let source_value = match source {
+        InlineImageSource::ImgDataUri => "img_data_uri",
+        InlineImageSource::SvgElement => "svg_element",
+    };
+    hash.aset(ruby.intern("source"), source_value)?;
+
+    let attrs = ruby.hash_new();
+    for (key, value) in attributes {
+        attrs.aset(key, value)?;
+    }
+    hash.aset(ruby.intern("attributes"), attrs)?;
+
+    Ok(hash.as_value())
+}
+
+fn warning_to_value(ruby: &Ruby, warning: InlineImageWarning) -> Result<Value, Error> {
+    let hash = ruby.hash_new();
+    hash.aset(ruby.intern("index"), warning.index as i64)?;
+    hash.aset(ruby.intern("message"), warning.message)?;
+    Ok(hash.as_value())
+}
+
+fn extraction_to_value(ruby: &Ruby, extraction: HtmlExtraction) -> Result<Value, Error> {
+    let hash = ruby.hash_new();
+    hash.aset(ruby.intern("markdown"), extraction.markdown)?;
+
+    let inline_images = ruby.ary_new();
+    for image in extraction.inline_images {
+        inline_images.push(inline_image_to_value(ruby, image)?)?;
+    }
+    hash.aset(ruby.intern("inline_images"), inline_images)?;
+
+    let warnings = ruby.ary_new();
+    for warning in extraction.warnings {
+        warnings.push(warning_to_value(ruby, warning)?)?;
+    }
+    hash.aset(ruby.intern("warnings"), warnings)?;
+
+    Ok(hash.as_value())
+}
+
+fn convert_fn(ruby: &Ruby, args: &[Value]) -> Result<String, Error> {
+    let parsed = scan_args::<(String,), (Option<Value>,), (), (), (), ()>(args)?;
+    let html = parsed.required.0;
+    let options = build_conversion_options(ruby, parsed.optional.0)?;
+
+    convert_inner(&html, Some(options)).map_err(conversion_error)
+}
+
+fn options_handle_fn(ruby: &Ruby, args: &[Value]) -> Result<OptionsHandle, Error> {
+    let parsed = scan_args::<(), (Option<Value>,), (), (), (), ()>(args)?;
+    let options = build_conversion_options(ruby, parsed.optional.0)?;
+    Ok(OptionsHandle(options))
+}
+
+fn convert_with_options_handle_fn(_ruby: &Ruby, args: &[Value]) -> Result<String, Error> {
+    let parsed = scan_args::<(String, &OptionsHandle), (), (), (), (), ()>(args)?;
+    let html = parsed.required.0;
+    let handle = parsed.required.1;
+    convert_inner(&html, Some(handle.0.clone())).map_err(conversion_error)
+}
+
+fn convert_with_inline_images_fn(ruby: &Ruby, args: &[Value]) -> Result<Value, Error> {
+    let parsed = scan_args::<(String,), (Option<Value>, Option<Value>), (), (), (), ()>(args)?;
+    let html = parsed.required.0;
+    let options = build_conversion_options(ruby, parsed.optional.0)?;
+    let config = build_inline_image_config(ruby, parsed.optional.1)?;
+
+    let extraction = convert_with_inline_images_inner(&html, Some(options), config).map_err(conversion_error)?;
+
+    extraction_to_value(ruby, extraction)
+}
+
+#[magnus::init]
+fn init(ruby: &Ruby) -> Result<(), Error> {
+    let module = ruby.define_module("HtmlToMarkdown")?;
+    module.define_singleton_method("convert", function!(convert_fn, -1))?;
+    module.define_singleton_method("options", function!(options_handle_fn, -1))?;
+    module.define_singleton_method("convert_with_options", function!(convert_with_options_handle_fn, -1))?;
+    module.define_singleton_method(
+        "convert_with_inline_images",
+        function!(convert_with_inline_images_fn, -1),
+    )?;
+
+    Ok(())
+}

data/lib/html_to_markdown/version.rb

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

data/lib/html_to_markdown.rb

@@ -7,9 +7,13 @@ module HtmlToMarkdown
   autoload :CLI, 'html_to_markdown/cli'
   autoload :CLIProxy, 'html_to_markdown/cli_proxy'
 
+  class Options; end # rubocop:disable Lint/EmptyClass
+
   class << self
     alias native_convert convert
     alias native_convert_with_inline_images convert_with_inline_images
+    alias native_options options
+    alias native_convert_with_options convert_with_options
   end
 
   module_function
@@ -18,7 +22,15 @@ module HtmlToMarkdown
     native_convert(html.to_s, options)
   end
 
+  def convert_with_options(html, options_handle)
+    native_convert_with_options(html.to_s, options_handle)
+  end
+
   def convert_with_inline_images(html, options = nil, image_config = nil)
     native_convert_with_inline_images(html.to_s, options, image_config)
   end
+
+  def options(options_hash = nil)
+    native_options(options_hash)
+  end
 end

data/spec/convert_spec.rb

@@ -26,4 +26,13 @@ RSpec.describe HtmlToMarkdown do
       expect(extraction[:inline_images].first[:description]).to eq('fake')
     end
   end
+
+  describe '.options' do
+    it 'returns a reusable options handle' do
+      handle = described_class.options(heading_style: :atx_closed)
+      expect(handle).to be_a(HtmlToMarkdown::Options)
+      result = described_class.convert_with_options('<h1>Hello</h1>', handle)
+      expect(result).to include('# Hello #')
+    end
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: html-to-markdown
 version: !ruby/object:Gem::Version
-  version: 2.6.5
+  version: 2.7.0
 platform: ruby
 authors:
 - Na'aman Hirschfeld
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-11-08 00:00:00.000000000 Z
+date: 2025-11-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rb_sys
@@ -47,8 +47,13 @@ files:
 - Gemfile.lock
 - README.md
 - Rakefile
+- bin/benchmark.rb
 - exe/html-to-markdown
 - ext/html-to-markdown-rb/extconf.rb
+- ext/html-to-markdown-rb/native/Cargo.toml
+- ext/html-to-markdown-rb/native/README.md
+- ext/html-to-markdown-rb/native/extconf.rb
+- ext/html-to-markdown-rb/native/src/lib.rs
 - html-to-markdown-rb.gemspec
 - lib/html_to_markdown.rb
 - lib/html_to_markdown/cli.rb